これは私のヘッドレス WordPress 移行シリーズのパート2です。ヘッドレス WordPress デプロイは本当の問題が始まるところで、DNS、SSL、画像、フォーム、リダイレクトがそれぞれ別の形で壊れます。パート1では Claude Code、Stitch MCP、Next.js を使ってフロントエンドを1日で作り直しました。この記事では、私が直面したデプロイ上の問題、その解決方法、そしてなぜ AI でも人間の判断が必要だったのかを紹介します。
誰も語らないヘッドレス WordPress デプロイの問題
フロントエンドを作るのは簡単です。私の経験では、ヘッドレス WordPress デプロイは、1つのサイトを2つのシステムに分割した瞬間から難しくなります。フロントエンドは Vercel、バックエンドは WordPress です。もはや単純な1つのスタックではありません。DNS、証明書、メディアURL、RESTエンドポイント、管理アクセスが、それぞれ別方向に引っ張り合います。
`optagonen.se` が Vercel に移ったとき、WordPress にアクセスしていたすべてのリクエストが、新しいフロントエンドに着地するようになりました。これで GraphQL、アップロード、Contact Form 7、管理アクセスが一度に壊れました。自分の ヘッドレス WordPress デプロイを計画しているなら、DNS を切り替える前に、そのブレークポイント（壊れる箇所）を設計しておく必要があります。
これはサンドボックスではなく、実際の本番移行で検証しました。教訓は明確でした。コードは速くできたが、インフラには時間がかかったのです。
ヘッドレス WordPress デプロイのための DNS 分割
最もきれいな解決策は、WordPress に独自のサブドメインを与えることでした：`wp.optagonen.se`。これにより、すべてを1つのオリジンに強制的にリバースプロキシすることなく、フロントエンドとバックエンドを分離できました。さらに、SSL とメディア配信のトラブルシューティングをするとき、アーキテクチャを理解しやすくなりました。
| ドメイン | 指し先 | 目的 |
|---|---|---|
| --- | --- | --- |
| `optagonen.se` | Vercel | Next.js のフロントエンド |
| `wp.optagonen.se` | オリジンサーバー | WordPress のバックエンド |
私は Hestia で `wp.optagonen.se` をエイリアスとして追加し、DNS の A レコードをオリジン IP に向け、フロントエンドの環境変数を更新しました：
この部分は紙の上では簡単です。しかし実際には、ヘッドレス WordPress デプロイが連鎖反応を引き起こしました。旧ドメインを前提にしていたあらゆるシステムが、新しいターゲットを必要としたのです。
ヘッドレス WordPress デプロイと SSL 証明書の失敗
最初に壊れたのは SSL でした。以前の Let's Encrypt 証明書は `optagonen.se` と `www.optagonen.se` だけをカバーしていたため、`https://wp.optagonen.se` は即座に失敗しました。これは当然の挙動です。Let's Encrypt はホスト名ごとにドメイン所有を検証し、証明書が一致しない場合、ブラウザは接続を拒否します。
Hestia の内蔵更新が失敗したのは、まだ HTTP-01 でメインドメインを検証しようとしていたからです。しかしメインドメインはすでに Vercel を指していました。Certbot も別の理由で失敗しました。Hestia が ACME チャレンジを横取りし、Certbot のサムプリントではなく自分のものを返していたのです。こうした競合は、AI が第一原理から推測できる類ではありません。パネルがどう振る舞うかを知る必要があります。
私は一時的に、nginx の include パスから Hestia の ACME チャレンジ設定を外し、`wp.optagonen.se` のみの証明書を発行してから、更新されたファイルを Hestia の SSL ディレクトリに戻すことで直しました。さらに、更新フックを追加して処理が自動のまま続くようにしました。
信頼性のために、Let's Encrypt と Certbot の公式ドキュメントに頼りました。これにより、再び本番に触る前に ACME の流れを確認できました。
なぜヘッドレス WordPress デプロイはサブドメインを拒否したのか
SSL が動くようになった後も、WordPress は新しいホストを受け入れませんでした。GraphQL データを返す代わりに `/wp-signup.php` にリダイレクトされたのです。これは、WordPress が受け取ったホストヘッダを気に入っていないことを示していました。
解決策は nginx の1つのディレクティブだけでした：
この1行で、ブラウザが `wp.optagonen.se` に留まっている間も、WordPress はあたかもリクエストがメインドメインから来たかのように振る舞うようになります。ヘッドレス WordPress デプロイでは、人が思う以上にこの種のホスト正規化が重要です。WordPress はサイトURLに関して非常に強いこだわりがあります。
この手の問題は、他の移行でも同じように見たことがあります。フロントエンドは動き、バックエンドは応答するのに、どこか1つのホストヘッダが一致していないだけで、セッションの流れが静かに壊れるのです。
ヘッドレス WordPress デプロイ後に画像が壊れた
デプロイ後、すべての画像が 502 エラーを返すようになりました。原因は、WordPress のメディアURLがまだ `/wp-content/uploads/...` を指しており、そのパスが今はオリジンサーバーではなく Vercel 側で解決されてしまったことです。私の構成では、問題は2箇所から来ていました。静的ファイル内のハードコードURLと、WPGraphQL が返す動的URLです。
まずハードコードURLを直しました。`https://optagonen.se/wp-content/uploads/` の参照を、6つのファイルすべてで `https://wp.optagonen.se/wp-content/uploads/` に置き換えました。これで約70の画像パスがカバーできました。
次に、Next.js のリライトで動的 GraphQL URL を修正しました：
これによりフロントエンドはきれいなままで、WordPress 内でメディアデータをリライトする必要がなくなりました。さらに、ブラウザは同じパスを要求し続け、サーバー側がプロキシを処理するため、ヘッドレス WordPress デプロイの保守性も上がります。
この種のシステム設計をさらに深掘りしたいなら、私の AI-powered WordPress migration workflow→ と、multi-agent content pipeline→ を読むことをおすすめします。これらの記事では、オートメーションの周りにインフラとコンテンツシステムをどう組み立てるかを示しています。
問い合わせフォーム、ID、そして最後のデプロイトラップ
Contact Form 7 は最初は問題なさそうに見えましたが、フォームが動かなくなりました。原因はフロントエンド側の ID が間違っていたからです。デフォルトのフォームIDは `1` でしたが、WordPress 内の実際のフォームは `8` でした。簡単な API チェックでそれが確認できました。
これは小さな修正でしたが重要です。ヘッドレス WordPress デプロイでは、ID が1つ間違っているだけで、バックエンドが健全でも動いていないように見えることがあります。私は `CF7_FORM_ID=8` を設定し直したところ、フォームはすぐにオンラインに戻りました。
だから私はいつも、フルフローを手動でテストします：
この順序は、ログだけから推測するよりも早く問題を見つけられます。
AI が助けてくれたこと、そして見落としたこと
Claude Code は素早く進めるのに役立ちましたが、理解を置き換えるものではありません。繰り返し作業はうまくやってくれました：設定ファイルの grep、nginx スニペットの生成、certbot コマンドの支援、画像URLの一括置換です。また、エラーの連鎖をメモリに保持してくれたので、1つの修正が別の問題を生んだときに時間を節約できました。
しかし AI は、完全なアーキテクチャを決めることはできませんでした。Hestia が ACME リクエストを横取りすることを知りませんでした。リバースプロキシではなくサブドメインを使うべきタイミングも知りませんでした。そしてダウンタイムを避けるための操作順序も知りませんでした。
ヘッドレス WordPress デプロイにおける AI の本当の価値はここです。診断を加速する一方で、スタックを理解している人間が必要です。私は AI automation systems for e-commerce→ を作る仕事でも、コンテンツパイプラインの作業でも、同じ原則を使っています。
デプロイ後の最終アーキテクチャ
修正後、スタックはきれいに分割された状態に落ち着きました：
| コンポーネント | 場所 | 目的 |
|---|---|---|
| --- | --- | --- |
| Next.js フロントエンド | Vercel | ページ配信とルーティング処理 |
| WordPress + WPGraphQL | `wp.optagonen.se` | コンテンツAPIとメディア保存 |
| Contact Form 7 | `wp.optagonen.se` | フォーム処理 |
| 画像プロキシ | Next.js のリライトルール | アップロードをオリジンへルーティング |
| フロントエンド SSL | Vercel | 自動管理 |
| バックエンド SSL | Certbot + 更新フック | 自動更新される証明書 |
この構造は安定していてデバッグしやすいです。さらに、WordPress 内の編集ワークフローを維持しつつ、フロントエンドを高速に保てます。ヘッドレス WordPress デプロイにおけるそのバランスこそが目標です。
このヘッドレス WordPress デプロイから得た教訓
移行から学んだことは次の通りです：
これらの教訓は、チュートリアルではなく実際の本番移行から得たものです。だから私は、デプロイにかける時間を、作り込みにかける時間と同じくらい確保するようになりました。
結論
ヘッドレス WordPress デプロイはコードのせいで難しいわけではありません。難しいのは、DNS、SSL、メディア、ホストヘッダがすべて互いに依存しているからです。この移行では、サブドメイン分割、証明書検証、画像配信、Contact Form 7 を修正し、AI がどこで役立ち、どこで止まるのかをはっきり学びました。
自分の移行を計画しているなら、まずフロントエンドの作り直しを読み、証明書フローを早めにテストし、公開前にすべてのメディアパスを検証してください。次にライブサイトを確認し、フォームが動くことを確かめ、バックエンドが WordPress が期待する通りに振る舞っているかを確認します。
より実践的なデプロイの分解が欲しいなら、関連投稿を読み、自分のスタックと比較してください。そうするのが、次の ヘッドレス WordPress デプロイでミスを避ける最速の方法です。
推奨画像 alt テキスト：