ブロックテンプレートが反映されないのはなぜですか？

たいていは、データベースに保存された版がファイルを上書きしているからです。サイトエディターでテンプレートを編集して保存した瞬間、WordPress は wp_template の投稿レコードを作り、テーマフォルダの .html ファイルの代わりにそれを配信します。その時点以降、ファイルをどれだけ編集してもフロントエンドには現れません。

サイトエディター版ではなくテーマのファイルを使わせるにはどうしますか？

外観からエディター、テンプレートと進み、対象のテンプレートを見つけて、そのオプションメニューからカスタマイズを解除、またはリセットを実行します。これでデータベースのレコードが削除され、制御がディスク上のファイルに戻ります。メニューにリセットではなく削除しか出ない場合、そのテンプレートはデータベースにしか存在せず、背後にファイルがありません。

ブロックテンプレートのファイルはテーマのどこに置きますか？

テンプレート全体はテーマルートの templates フォルダに、再利用する部品は parts フォルダに置きます。どちらも拡張子は .html、ファイル名は小文字で、アンダースコアではなくハイフンを使います。またブロックテーマには templates/index.html が必須で、これがないと WordPress はそのテーマをブロックテーマとして扱いません。

テンプレートとテンプレートパーツは何が違うのですか？

テンプレートはページ全体を描画するもので、何を表示しているかに応じてテンプレート階層によって選ばれます。テンプレートパーツはヘッダーやフッターのような断片で、テンプレートから読み込まれます。ヘッダーのパーツを編集すると、それを含むすべてのテンプレートが変わります。パーツの編集が意図しない場所に効いたように見えるのは、これが理由です。

キャッシュが原因でブロックテンプレートが更新されないことはありますか？

あることはありますが、可能性としては最も低く、最後に確認すべきものです。ページキャッシュや永続オブジェクトキャッシュが古いマークアップを保持することはあるので、結論を出す前に両方をパージしてください。OPcache のクリアはここでは無意味です。ブロックテンプレートは .html ファイルで、そもそも PHP にコンパイルされないからです。

スラッグ指定のテンプレートが急に効かなくなったのはなぜですか？

スラッグ指定のテンプレートは、リクエスト時点の投稿スラッグと照合されます。ページ名を変えるとスラッグが変わるため、ページが about-us になった時点で page-about.html は黙って一致しなくなります。カテゴリーやタグのテンプレートも同様です。ファイル名を新しいスラッグに合わせて変更するか、投稿エディターのサイドバーでテンプレートを明示的に指定してください。

ブロックテンプレートが反映されない？まずデータベースを疑う

テンプレートファイルが無視されている原因は、ほぼ確実にデータベース上のコピーが勝っていることです。サイトエディターでテンプレートを開いて保存を押した瞬間、WordPress は wp_template の投稿レコードを書き込み、以後はテーマフォルダの .html ファイルではなくそのレコードが配信されます。その後にファイルへ加えた編集は、すべてフロントエンドに現れません。このレコードを消すことが解決策であり、テンプレート階層やファイル名、キャッシュに触れる前に最初に確認すべきことです。

データベース上のコピーがあるか確認する

外観 → エディター → テンプレート を開きます。WordPress がデータベースから配信しているテンプレートには、一覧上で印が付きます。WordPress のバージョンによって「カスタマイズ済み」というバッジが付くか、「カスタマイズ済み」のフィルターに表示されます。そのバッジがすべての答えです。付いていれば、あなたのファイルは使われていません。

同じことはコマンドラインからも確認できます。そのほうが速く、サイトエディターの挙動がおかしいときでも動きます。

wp post list --post_type=wp_template --fields=ID,post_name,post_status,post_title
wp post list --post_type=wp_template_part --fields=ID,post_name,post_status,post_title

各行がデータベースによる上書きです。post_name はテンプレートのスラッグと一致するので、single という行があれば templates/single.html を覆い隠しています。

つまずきやすい点が 1 つあります。これらのレコードは、パスではなくタクソノミーのタームでテーマに紐づいています。テーマのフォルダ名を変更すると、保存されたテンプレートはデータベースに残ったまま有効なテーマと一致しなくなり、サイトは突然ファイルにフォールバックします。これは「ファイルが無視される」ではなく「カスタマイズが消えた」ように見えますが、仕組みは同じで症状が逆になっただけです。

消す

サイトエディターでテンプレートのオプションメニュー（横の三点リーダー）を開き、カスタマイズを解除 を選びます。バージョンによっては リセット と表示されます。これでデータベースのレコードが削除され、制御はディスク上のファイルに戻ります。

メニューにカスタマイズを解除やリセットではなく削除しか出ない場合、そのテンプレートはデータベースにしか存在せず、背後にファイルがありません。削除するとテンプレートごとなくなり、WordPress は階層をたどって下位のものにフォールバックします。

WP-CLI からは、上の一覧で得た ID を使います。

wp post delete 482 --force

ここでのコストには正直でいてください。カスタマイズの解除は、そのテンプレートについてサイトエディターで作ったものを完全に破棄し、元に戻せません。サイトエディター版に本当の作業内容が入っているなら、先にブロックマークアップを取り出しておきます。エディターでテンプレートを開き、コードエディター表示に切り替えて、その内容を .html ファイルに貼り付けてください。こうすればファイルが正となり、何も失われません。

WordPress がテンプレートを選ぶ仕組み

ブロックテーマはクラシックテーマとまったく同じ階層のロジックを使います。違いは、テーマルートの .php ファイルではなく templates/ の .html ファイルであることだけです。WordPress は最も具体的なものから最も一般的なものへとたどり、最初に見つかったファイルを使います。

表示しているもの	確認される順序
個別投稿	`single-post-{slug}.html` → `single-post.html` → `single.html` → `singular.html` → `index.html`
固定ページ	`page-{slug}.html` → `page-{id}.html` → `page.html` → `singular.html` → `index.html`
カテゴリーアーカイブ	`category-{slug}.html` → `category-{id}.html` → `category.html` → `archive.html` → `index.html`
カスタム投稿タイプ	`single-{post-type}.html` → `single.html` → `singular.html` → `index.html`
404 ページ	`404.html` → `index.html`

これを完全に無効化するものが 2 つあります。1 つは上で説明したデータベースのレコード。もう 1 つは、投稿やページに直接割り当てられたテンプレートです。投稿エディターを開き、サイドバーのテンプレートパネルを見て、特定のものが選ばれていないか確認してください。明示的な割り当ては常に階層に勝ち、そして探しに行かない限り目に入りません。

スラッグ指定のテンプレートの脆さは、覚えておく価値があります。page-about.html は、そのページのスラッグが about である間だけ一致します。ページを about-us に変更すると、警告もエラーもなくテンプレートは適用されなくなります。

テンプレートとテンプレートパーツ

テンプレート はビュー全体を描画し、階層によって選ばれます。テンプレートパーツ はヘッダー、フッター、サイドバーといった断片で、テンプレートが読み込むものです。パーツは parts/ に、テンプレートは templates/ に置かれ、データベース上でも wp_template_part レコードとして別々に保存されます。

よくある混乱がこれです。ヘッダーを編集したら、触るつもりのなかったページにも変更が現れた。これは正しい挙動です。1 つのパーツは、それを含むすべてのテンプレートで共有されています。特定のテンプレートだけヘッダーを変えたいなら、2 つ目のパーツファイルと、それを参照するテンプレートが必要です。共有されているほうを編集しても、テンプレートごとの差分は決して得られません。

逆のパターンも起きます。ページ全体のレイアウトを parts/ に入れて、なぜ階層が拾ってくれないのかと悩むケースです。パーツはそもそも階層の候補ではなく、そこへ直接ルーティングされることはありません。

ファイル名と置き場所

もっと特殊な原因を疑う前に、ここを確認してください。

フォルダはテーマルートの templates/（複数形）です。template/ でも block-templates/ でもありません。block-templates/ は、ブロックテーマがコアに入る前の Gutenberg プラグイン時代の正しい名前で、今もそれを載せたチュートリアルは大量にありますが、現在の WordPress では動きません。
テンプレートパーツは parts/ に置きます。template-parts/ ではありません（こちらはクラシックテーマで PHP の部品を置く慣習です）。
拡張子は .html です。templates/ に置いた .php ファイルは無視されます。
ファイル名は小文字で、ハイフンを使います。single-Post.html や single_post.html は一致しません。macOS のような大文字小文字を区別しないファイルシステムではローカルで動いてしまい、Linux サーバーで壊れます。典型的な「自分の環境では動く」系の失敗です。
templates/index.html は必須です。これがないと WordPress はそのテーマをブロックテーマとして分類せず、サイトエディター自体が表示されないこともあります。
子テーマで作業している場合、子テーマのテンプレートが親より優先されます。子テーマに残っていた古いファイルが、あなたが編集している親のファイルに静かに勝ちます。

投稿エディターで選択できるようにしたいカスタムテンプレートは、theme.json の customTemplates に、ファイルのベース名、人間が読めるタイトル、適用する投稿タイプを記述する必要もあります。この記述がないと、ファイルは存在してもテンプレートパネルには決して現れません。

キャッシュ — 確認は最後に

キャッシュの影響は実在しますが、原因としては最も可能性が低く、最初にここへ手を伸ばすと午後がまるごと消えます。

ページキャッシュをパージし、Redis や Memcached のような永続オブジェクトキャッシュを使っているならそれもフラッシュしてください。テンプレート解決の結果がそこに保持されることがあります。そのうえで、ブラウザキャッシュを回避して再読み込みします。

役に立たないもの: OPcache のクリアです。ブロックテンプレートは .html ファイルで PHP にコンパイルされないため、OPcache は無関係です。以前 OPcache のフラッシュで直ったように見えたなら、同時に別の何かが変わっていたはずです。

それでも直らないとき

データベースにレコードがなく、ファイル名も正しく、投稿にテンプレートの明示指定もなく、キャッシュもパージ済みなら、次はプラグインを見ます。テンプレート解決にフィルターをかけるもの — ページビルダー、会員制プラグイン、多言語プラグイン、LMS — は、リクエストの後半で自前のテンプレートに差し替えられます。デフォルトのブロックテーマに切り替え、プラグインを無効化した状態でテストし、そこから 1 つずつ有効に戻してください。

なお、テンプレートは適用されているのに中身が空で描画される場合は、別の問題です。ファイル内のブロックマークアップが正しいか確認してください。ブロックコメントが壊れていると、エディターはエラーを出さずに黙ってコンテンツを取り除くことがあります。