ヘッドレスCMSで更新がすぐ反映されないときの設計｜待ち時間を数十秒に落とす仕組みと運用の伝え方

WordPressの管理画面で記事を保存した。プレビューでは正しく表示されている。それなのに、公開サイトを見に行くと変わっていない——ヘッドレス構成（編集用のWordPressと表示用の静的サイトを分けた構成）のサイトで、これは故障ではなく仕様である場合がほとんどです。

先に結論を書きます。ヘッドレス構成の「反映されない」への対処は、次の3つのどれか（または組み合わせ）です。

方式	反映までの時間	向いている場面
定期ビルド（cron）＋事前説明	数分〜30分	更新頻度が低い。サーバーに常駐処理を置けない
保存フックからビルドを直接起動	数十秒	更新する人が結果をすぐ確認したい。国内サーバー同士で完結できる
手動の即時ビルドコマンドを用意	即時（操作した時だけ）	制作会社側が更新代行する運用

そして方式がどれであっても、納品時に「保存してから公開サイトに映るまでの時間」を必ず説明すること。ここを省くと、サイトが正常に動いていてもクライアントには「壊れている」と映ります。実際にどういうことが起きるか、自社と実案件の数字で説明します。

なぜ「保存したのに映らない」が起こるのか

通常のWordPressは、記事を保存すればその瞬間から公開ページに反映されます。データベースを書き換えれば、次のアクセスからは新しい内容が表示される仕組みだからです。

ヘッドレス構成は違います。編集用のWordPressはデータベースを書き換えるだけで、訪問者が見るのはビルド（静的HTMLの生成）を経て配置されたファイルです。つまり「保存」と「公開」のあいだに、ビルドという工程が1つ挟まっています。この工程が動くタイミングが、反映までの待ち時間を決めます。

表示速度と安全性のためにあえて挟んでいる工程なので、これ自体は欠点ではありません。問題は、待ち時間の存在が編集画面のどこにも表示されないことです。保存ボタンは一瞬で成功し、エラーも出ない。それなのに公開サイトは古いまま。更新した本人から見ると「操作は成功したのに結果が変わらない」という、最も原因の見当がつかない状態になります。

実例：正常に動いているサイトに「アップできない」という連絡が来る

自社サイトも、制作したクライアントのサイトも、WordPress＋静的サイトジェネレーターのヘッドレス構成で、30分間隔の定期処理が更新を検知してビルドする方式を採っています。コンテンツの最終更新を前回と比較し、変化があったときだけビルドが走る設計で、ビルド自体は90秒ほどです。

この方式で運用していたクライアントサイトで、実際にあった例です。16時29分に「ブログのお知らせがアップできない」という連絡が入りました。ログを確認すると、16時30分04秒に定期処理が更新を検知し、8秒で本番に反映されていました。つまり連絡をもらった約1分後には公開されており、システムは設計どおりに動いていたのです。

それでも連絡が来た理由は単純で、保存した直後に公開サイトを見に行くと、必ずまだ映っていないからです。定期ビルドの間隔が30分なら、保存の直後に確認する人は毎回「変わっていない」画面を見ることになります。何度更新しても同じなので、体験としては毎回壊れているのと区別がつきません。

ここから引き出せる教訓は2つあります。1つは、「反映されない」という報告を受けたら、まずビルドのログと完了時刻を確認すること。故障を疑って設定を触り始める前に、単に「まだビルドが走っていないだけ」を除外します。もう1つは、そもそもこの報告が発生しない設計・説明にしておくことです。次で具体的に書きます。

待ち時間を約40秒に落とす：保存フックからビルドを直接起動する

この連絡を受けて、当該のクライアントサイト（医療機関）では最大30分の待ち時間を保存から約40秒に短縮しました。WordPressの保存イベントをフックにして、サーバー内のビルドスクリプトを直接起動する方式です。編集用WordPressと表示側が同じ国内サーバーに同居していれば、外部サービスを経由せずに完結できます。

実装で効いた設計判断は次のとおりです。同じ構成を組む場合は、そのまま判断基準として使えます。

1. 発火条件を絞る。 公開状態に関わる保存と削除だけでビルドを起動し、リビジョンや自動保存では起動しない。ここを絞らないと、編集中の自動保存のたびにビルドが走ります。

2. 連続保存への対策は「間引き」ではなく「まとめて拾い直す」。 担当者は記事を数分のあいだに何度も保存します。対策として「一定時間内の保存は無視する」という単純な間引きを入れると、最後の保存が捨てられて古い内容のまま公開されることが起こり得ます。それでは「更新が反映されない」というもとの問題を自分で作り直すことになります。採ったのは3段構えです。①保存が落ち着くまで30秒待ってから起動する ②同時に2本のビルドが走らないよう排他制御する ③ビルド完了後に、ビルド中に入った保存がないかを再チェックして拾い直す（上限つき）。実測では、連続3回保存してもビルドは1回だけ走り、最新の内容が反映されました。

3. 保存の応答を待たせない。 ビルドを裏で起動する作りにして、保存ボタンの応答は1秒以内。管理画面の操作感は通常のWordPressと変わりません。

4. 定期ビルドは保険として残す。 即時化が成功しても、30分間隔の定期処理は止めない。フック側に何かあっても、最大30分で必ず追いつくためです。即時反映という「速い経路」と定期処理という「確実な経路」の二重化で、どちらかが死んでも更新は届きます。

組むときに想定しておくべき落とし穴

同じ構成を実装する際に、あらかじめ設計へ織り込んでおくべき点を挙げます。いずれも実案件・自社サイトの運用で確認したものです。

Webサーバー経由で起動されるスクリプトは、環境変数が空になり得る。 ターミナルから手で実行すると動くビルドスクリプトが、WordPressのフックから起動すると即座に落ちる、ということが起こります。ホームディレクトリやPATHといった環境変数が、Webサーバーのプロセスでは設定されていないためです。起動側のスクリプトで必要な環境変数を明示的に埋めておくと防げます。

反映の検証は、ビルドの完了時刻を確認してから行う。 ビルドが終わる前に公開サイトを見て「反映されていない」と判定してしまう誤りは、実装者側でも起こります。サーバー前段のキャッシュが古い応答を返す場合もあるため、「ログ上のビルド完了時刻→その後に実ページを取得」という順序を検証の型にしておきます。

記事の削除は、追加よりも事故が起きやすい。 静的サイトは「新しいファイルを置く」ことは得意ですが、削除された記事の古いHTMLはビルド後もサーバーに残り、URLを直接叩くと表示され続けます。掃除の処理を入れる場合、「生成物に無いファイルを消す」という素朴な判定にすると、手動で配置した転送設定ファイルなどのビルド対象外の重要ファイルまで削除対象に入ります。対象を特定の拡張子に限定する、除外リストを持つ、といった安全弁を最初から設計に含めてください。削除の検証は「消えたこと」だけでなく「消してはいけないものが残っていること」まで確認して完了です。

納品時の「伝え方」まで含めて設計

冒頭の表のどの方式を選ぶ場合でも、納品時に次のどちらかを必ず実施することをおすすめします。

①待ち時間を事前に説明する。 「保存してから公開サイトに映るまで最大◯分かかります。保存直後は前の内容が表示されますが、故障ではありません」という1段落を、操作マニュアルの保存手順の直後に入れます。説明の位置が重要で、マニュアルの末尾の注意書きでは読まれません。

②即時反映にする。 更新頻度が高い、またはお知らせを出してすぐ確認したい運用なら、保存フック方式で数十秒まで縮めます。体感として「保存して、ひと呼吸おいて確認すると映っている」なら、待ち時間の説明はほぼ不要になります。

判断基準はシンプルで、更新する人が「保存した直後に自分で確認しに行くか」です。確認しに行く運用なら即時化の価値が高く、月に数回の更新を制作会社側で代行するなら定期ビルド＋説明で十分です。

まとめ

• ヘッドレス構成の「更新が反映されない」は、多くの場合は故障ではなくビルド待ち。まずビルドのログと完了時刻を確認する
• 待ち時間は設計で縮められる。保存フックからビルドを直接起動する方式で、実測で最大30分→約40秒になった
• 連続保存対策は「間引き」にしない。最後の保存を捨てると、直そうとした問題を自分で再発させる。落ち着き待ち・排他制御・完了後の拾い直しの3段構えにする
• 即時化しても定期ビルドは保険で残す。速い経路と確実な経路の二重化
• どの方式でも、保存から公開までの時間差は納品時に必ず説明する。正常動作でも、説明がなければクライアントには不具合に見える

ヘッドレス構成は表示速度とセキュリティで通常構成より有利ですが、その利点は「更新体験の設計」まで含めて初めて成立します。構成の技術選定についてはWordPress＋Astroのヘッドレス構成が中小企業サイトに向いている理由で、反映されない症状のうち配信元の食い違いが原因のケースはWordPressでCSSを直したのに反映されないときで扱っています。あわせてどうぞ。