カスタムタクソノミーアーカイブが404になる原因と対処

結論
原因・仕組み
手順（サンプルコード）
動作確認（検証環境と結果）
カスタムタクソノミーアーカイブが404になる原因と対処の注意点
カスタムタクソノミーアーカイブが404になる原因と対処でよくあるミス
カスタムタクソノミーアーカイブが404になる原因と対処のチェックリスト
カスタムタクソノミーアーカイブが404になる原因と対処のFAQ（よくある質問）
筆者の見解（カスタムタクソノミーアーカイブが404になる原因と対処）
カスタムタクソノミーアーカイブが404になる原因と対処の関連項目
出典（一次情報）

結論

カスタムタクソノミーのアーカイブ（例: /genre/rock/）が404になる主な原因は次の3つです。

リライトルールが更新されていない。登録直後は、保存済みのルールに新しい URL が入っていません。
register_taxonomy() を init フックで呼んでいない。
rewrite や public / publicly_queryable の設定が意図と違う。

最短の対処は、管理画面の「設定 → パーマリンク」で「変更を保存」を押すことです。コードで対応するなら、プラグインの有効化時に1回だけ flush_rewrite_rules() を呼びます。テーマの functions.php で毎回呼ぶのは避けます。

原因・仕組み

WordPress は、URL とクエリの対応表（リライトルール）を rewrite_rules オプションに保存し、リクエストのたびにそれを参照します。タクソノミーを登録すると、メモリ上の登録情報は増えますが、保存済みの対応表は自動では作り直されません。そのため、get_term_link() は /genre/rock/ というURLを返すのに、アクセスすると404になります。

公式リファレンスでも、登録後は「リライトルールのフラッシュが必要な場合がある」と書かれています。また、タクソノミー名は1〜32文字で、小文字英数字・ダッシュ・アンダースコアのみです。

手順（サンプルコード）

add_action( 'init', function () {
    register_taxonomy( 'genre', 'post', array(
        'label'        => 'ジャンル',
        'public'       => true,
        'hierarchical' => true,
        'show_in_rest' => true,
        'rewrite'      => array( 'slug' => 'genre' ),
    ) );
} );

プラグインとして配布するなら、登録処理を関数にして、有効化時にも呼びます。

function my_register_genre() {
    register_taxonomy( 'genre', 'post', array(
        'public' => true, 'hierarchical' => true,
        'rewrite' => array( 'slug' => 'genre' ),
    ) );
}
add_action( 'init', 'my_register_genre' );

register_activation_hook( __FILE__, function () {
    my_register_genre();      // 先に登録してから
    flush_rewrite_rules();    // ルールを作り直す
} );

テーマの場合は、管理画面で一度パーマリンクを保存します。ソース管理に含めたい場合は、delete_option( 'rewrite_rules' ) で保存済みルールを消して、WordPress に次回の適切なタイミングで再生成させる方法もあります。

動作確認（検証環境と結果）

WordPress 7.1.2（ja）／PHP 8.2.12／MariaDB 10.4.32、パーマリンクは /%postname%/。run.php から実行しました（tests フォルダの p3.php）。

link: http://localhost/genre/rock/
rule for genre/ present before flush: false
after flush: genre/([^/]+)/feed/(feed|rdf|rss|rss2|atom)/?$ ...

登録直後は、保存済みの rewrite_rules に genre/ 始まりのルールがありませんでした（false）。URL 自体は get_term_link() が生成できています。
flush_rewrite_rules( false ) のあとには、genre/([^/]+)/... のルールが追加されました。
33文字以上の名前では taxonomy_length_invalid エラー（WP_Error）が返り、「タクソノミー名の長さは1から32文字でなければいけません」という通知が出ました。
ブラウザでの実アクセス（HTTP 404 から 200 への変化）は、この CLI 環境では確認していません。