【ITニュース解説】My deploy said Success. It went to a URL nobody visits.

「デプロイ」とは、自分が書いたプログラムやウェブサイトのファイルを、インターネット上に公開されているサーバーに配置し、実際に利用できるようにする作業のことだ。このデプロイ作業が「成功しました」と表示されたにもかかわらず、ウェブサイトにアクセスしても内容が変わっていない、という不可解な状況に直面することがある。これは、システムエンジニアを目指す上で誰もが一度は遭遇する可能性のある、非常に重要な問題だ。

今回のケースでは、開発者がウェブサイトの変更をデプロイし、ツールから「成功しました」というメッセージを受け取った。しかし、実際のサイトを確認すると、変更がまったく反映されていなかった。これは、キャッシュの問題でも、古い情報が表示されているわけでもなく、単純に「変更がそこにはない」という状態だった。このデプロイは、開発者が意図しない「誰も訪れない場所」に成功していたのだ。

この問題の根源は、Cloudflareというクラウドサービスにおける「Pagesプロジェクト」と「Workerプロジェクト」という二つの異なるサービスが、たまたま同じ名前で存在していたことにあった。開発者の環境では、「my-project」という名前のPagesプロジェクトがあり、これにウェブサイトの公開用ドメイン（例: mydomain.com）が紐付けられていた。一方、同じ「my-project」という名前のWorkerプロジェクトも存在し、こちらはコードベースの設定ファイル（wrangler.jsonc）が参照するデプロイ先だった。

開発者が使用したデプロイコマンド「wrangler deploy」は、Cloudflare Workerプロジェクトにファイルを公開するためのものだ。このコマンドはWorkerプロジェクトへのファイルのアップロードを正常に完了し、「成功」と報告した。しかし、ウェブサイトにアクセスする際に使用されるカスタムドメインは、実はPagesプロジェクトに紐付けられていたため、Workerプロジェクトにデプロイされた変更は、ウェブサイトに表示されることはなかった。つまり、デプロイツールは「アップロードは成功した」という真実を伝えたが、それは開発者が「ウェブサイトに反映されたか」という意図で尋ねた質問とは異なる答えだったのだ。

自分がデプロイしようとしているドメインが、実際にはどのプロジェクトに紐付いているかを確認する方法は重要だ。設定ファイルの内容から推測するのではなく、直接CloudflareのAPIに問い合わせるのが確実である。具体的には、「npx wrangler pages project list」というコマンドを実行すると、各Pagesプロジェクトに紐付いているドメインの一覧が表示される。もし自分のドメインがPagesプロジェクトにリストされていれば、wrangler deploy コマンドは間違ったターゲットにデプロイしていることになる。

また、デプロイが実際に反映されたかを素早く確認する別の方法もある。それは、ビルド（ウェブサイトのファイルを生成する工程）によって作られたアセットファイル（JavaScriptやCSSなど）のファイル名と、現在ライブサイトで参照されているアセットファイルのファイル名を比較することだ。現代のウェブ開発では、これらのアセットファイルには内容が変わるたびに一意のハッシュ値が付加されたファイル名（例: index-41b206cb.js）が付けられることが多い。もし、手元のビルド済みファイルとライブサイトが参照しているファイルのハッシュが異なっていれば、それはウェブサイトに新しい変更がまだ反映されていない明確な証拠となる。これは、デプロイログが何を言っていようと、確実な答えを示してくれる方法だ。

次に、正しいデプロイ先であるPagesプロジェクトにデプロイしようとした際にも、別の問題が発生した。Pagesプロジェクトへのデプロイコマンドは「wrangler pages deploy」だ。しかし、このコマンドを実行すると、プロジェクトのルートディレクトリにある「wrangler.jsonc」という設定ファイルの中にWorkerプロジェクト用の設定が含まれているため、Pagesデプロイが拒否されてしまう。さらに、Pagesデプロイでは、設定ファイルを別のパスに指定するオプション（-c）がサポートされていない。

この問題を回避するために、一時的ながらも有効な解決策が取られた。それは、デプロイを実行する前に「wrangler.jsonc」ファイルを一時的に別の名前に変更し（例: wrangler.worker.jsonc）、Pagesデプロイを成功させた後、元のファイル名に戻すというものだ。これは洗練された方法とは言えないが、機能することは確認されている。ただし、このような操作は手動で行うとミスや忘れが生じやすいため、自動化スクリプトに組み込むべきだ。これにより、デプロイが失敗した場合でも設定ファイルが誤った名前のまま放置されるような事態を防ぐことができる。

さらに、CLIツールが設定ファイルを自動で探索する挙動が原因で発生する別の落とし穴もある。今回のケースでは、特定のサブディレクトリ内でシークレット情報（APIキーなどの秘密情報）を設定しようとした際、「npx wrangler secret put MY_SECRET」というコマンドが使われた。しかし、このサブディレクトリには、そのディレクトリ専用のWorkerプロジェクトの設定ファイル（wrangler.toml）があったにもかかわらず、Wranglerツールはディレクトリを遡って親ディレクトリのWorkerプロジェクトの設定を読み込んでしまい、結果的に意図しないWorkerにシークレットが設定されてしまったのだ。

この間違いに気づく手がかりは、「wrangler secret list」コマンドで確認できるシークレットの数だった。意図したWorkerには10個のシークレットが登録されているはずなのに、リストには1個しか表示されなかった。これは、ツールが間違ったWorkerと通信している明確なサインだった。この問題の解決策は、デプロイやシークレット設定などのコマンドを実行する際、常に「-c wrangler.toml」のように、どの設定ファイルを使用するかを明示的に指定することだ。CLIツールが自動で設定ファイルを解決する挙動は便利な反面、今回のように意図しない結果を招く可能性があるため、注意が必要だ。

最後に、デプロイが正しいターゲットに成功し、設定も適切であるにもかかわらず、まだウェブサイトに古い内容が表示されるという問題が残っていた。これは、ウェブサイトのキャッシュが原因だった。新しいアセットファイルはサーバーにアップロードされ、アクセスすれば正しく取得できる状態になっていたが、それらの新しいアセットを参照するHTMLファイル自体が、ブラウザやCDN（コンテンツ配信ネットワーク）によってキャッシュされており、古いバージョンが提供され続けていたのだ。

この状況で、アセットのURLにランダムなクエリパラメータ（例: ?cb=$RANDOM）を付加してキャッシュを回避しようとしても、HTMLファイルが古い内容のままであれば効果がない。HTMLファイル自体が古いアセットのハッシュ値を含んでいるため、新しいアセットファイルへの参照が行われないからだ。この問題は、CloudflareのAPIを通じてキャッシュを強制的にパージ（削除）することで解決できる。具体的には、CloudflareのAPIに対して、ゾーン全体のキャッシュを削除するリクエストを送信する。これにより、CDNに保存されていた古いコンテンツが強制的にクリアされ、ユーザーには最新のコンテンツが提供されるようになる。

これらの経験から得られる教訓は非常に大きい。まず、「デプロイ成功」というメッセージは、「ファイルがアップロードされた」という事実を伝えるものであり、「ユーザーに最新の内容が公開された」ことを意味するわけではない。これらはまったく異なる質問であり、本当に重要なのは後者だ。

次に、デプロイが成功したかどうかを検証するには、単にログメッセージを信じるのではなく、実際にビルド出力とライブサイトが提供している内容を比較することが不可欠だ。特に、ハッシュ化されたファイル名を持つアセットを比較する方法は非常に効率的で確実だ。

そして、コマンドラインツールが設定ファイルを自動的に検索して解決する際、意図しない設定を参照する可能性があるため、常に適切な設定ファイルを明示的に指定する習慣をつけるべきだ。エラーを出さずに間違った操作を「成功」と報告するサイレントな挙動は、エラーとして停止するよりも厄介な結果を招くことがある。

最後に、もしツールが「成功」と報告しているにもかかわらず、現実の状況がそれに反している場合、自分がツールに尋ねた質問と、ツールが実際に答えた質問が異なっている可能性を疑うべきだ。システムが示す「成功」の定義と、自分が求める「成功」の定義に齟齬がないか、常に注意深く確認する必要がある。今回のケースでは、コードの変更自体は最初から正しかった。問題は、そのコードを正しく公開するためのデプロイプロセス全体にあったのだ。