【ITニュース解説】The Deployment Failure That Only Shows Up on a Clean Clone

あるWebサイト「DukoTools」の開発中に起きた、デプロイ失敗という問題から得られた重要な教訓について解説する。この事例は、「自分のパソコンでは動くのに、公開環境ではなぜか動かない」という、開発者が直面しがちな典型的な課題を浮き彫りにしている。

DukoToolsでは、多くの新しいツール（機能）が次々と追加されていた。開発者は通常、一つのツールの部品（コンポーネント）を作り、それがWebサイトのどこで表示されるかを設定するファイル（ルーターファイル）に組み込み、自分のパソコンで動作を確認するという流れで作業を進めていた。この作業は少しずつ、順調に進んでいるように見えた。しかし、ここで一つの問題があった。それは、新しく作ったツールが完全に動作する状態になっても、その変更すべてをGitというバージョン管理システムにすぐに記録（コミット）していなかった点だ。つまり、自分のパソコンには新しいツールのファイルが存在するが、Gitにはまだ記録されていない、という状態がたびたび発生していたのである。

この状況で、ある日、開発者はWebサイトの国際化（i18n）に関する、全く別の問題を修正するために、共有のルーターファイルを編集した。この修正自体は正しく、自分のパソコンでプログラムを動かす（ビルドする）と、問題なく成功した。そのため、この変更をGitに記録し、Webサイトを公開するサービス（Vercel）へデプロイ（展開）する作業を開始した。しかし、Vercel上でのビルドは失敗してしまったのだ。

なぜ、自分のパソコンでは成功したのに、Vercelでは失敗したのだろうか。その根本原因は、「自分のパソコンの環境」と「Vercelのビルド環境」の違いにあった。自分のパソコンでは、まだGitに記録されていない新しいツールのファイルが、ハードディスク上に実際に存在していた。そのため、ルーターファイルがこれらの未コミットのツールを参照していても、参照先のファイルが見つかるため、問題なくビルドが成功したのだ。

一方、Vercelのような公開環境でのビルドは、常にGitリポジトリに記録されているファイルだけを使って行われる。Vercelのビルド環境は、あたかもまっさらな状態からGitリポジトリを丸ごとコピー（クローン）し、その中にあるファイルだけでビルドを試みる。このとき、自分のパソコンにしか存在せず、Gitにコミットされていなかった新しいツールのファイルは、Vercelのビルド環境には存在しない。にもかかわらず、ルーターファイルには、その存在しないツールへの参照（「このツールを読み込む」という指示や、「このツールを表示する」という設定）がすでに書かれていた。結果として、Vercelのビルドは、参照先のファイルが見つからないというエラーで停止してしまったのである。

これは、ルーターファイルが複数の機能から触られる「共有の場所」であるにもかかわらず、その中で「この機能が完成したら、その参照をルーターファイルに加える」という厳密なルールが守られていなかったために起こった問題だ。個々のツールは独立して作られたが、ルーターファイルへの追加や、ツールの設定ファイル、翻訳ファイルといった関連する変更が、常に一連の流れとしてGitにコミットされていなかったのだ。

この問題の修正自体は、ルーターファイルの中から、まだGitにコミットされていないツールの参照行を削除するという、比較的簡単なものだった。しかし、修正以上に重要なのは、その「検証方法」だった。

開発者はまず、git stashというGitの機能を使って、自分が加えた修正を一時的に取り除いた。その状態でビルドを試みると、やはり同じエラーで失敗した。これにより、この問題が自分の修正によって引き起こされたのではなく、以前から存在していたことが証明された。これは、「私が壊した」のか「すでに壊れていたものを私が露呈させただけなのか」という重要な区別をつける上で非常に役立つ。

さらに決定的な検証として、開発者は一時的なディレクトリにGitリポジトリをまっさらな状態でクローンし、そこでビルドを試みた。これは、Vercelのビルド環境を自分のパソコン上で再現する最も確実な方法だ。自分のパソコンにたまたま残っていたファイルや、インストール済みのプログラムの残骸などが一切ない、完全にクリーンな環境でビルドが成功することを確認したのだ。これでようやく、修正が正しく、公開環境でも問題なく動作することが保証された。

この経験から得られる教訓は、システムエンジニアを目指す上で非常に価値がある。 一つは、「ローカルでビルドが成功する」ことと「クリーンな環境（Gitリポジトリのみ）からビルドが成功する」ことは全く異なる、という点だ。公開環境でのデプロイは後者の条件で行われるため、常にその視点を持って開発やテストを行う必要がある。 もう一つは、機能を開発する際は、それがたとえ複数のファイルにまたがる変更であっても、必要なすべてのファイルを一つのまとまり（アトミックな単位）として同時にGitにコミットするべき、という点だ。今回の事例のように、一部の変更だけが先にコミットされてしまうと、今回のような矛盾が生じやすい。コンポーネント本体、ルーターファイルへの登録、関連する設定や翻訳ファイルなど、一つの機能が完成するために必要なものはすべてセットでコミットすることが重要だ。 また、バグを修正する前には、そのバグが本当に自分の変更によって引き起こされたのか、それとも以前から存在していたのかを、git stashのようなツールを使って確認する習慣も非常に役立つ。これにより、自信を持って修正を適用し、不必要な混乱を避けることができる。 共有のファイルに変更を加える際は、特に慎重になるべきだ。まだ完成していない機能への参照を安易に共有ファイルに追加してしまうと、今回のような「時限爆弾」を仕掛けてしまうことになる。

この経験を通じて、開発者はより堅牢な開発プロセスと、デプロイの信頼性を高めるための重要な学びを得ることができた。