【ITニュース解説】Un 500 sur toutes les pages : deux serveurs de dev, un seul dossier de cache

ウェブサイト開発の現場では、予期せぬエラーに遭遇することがよくある。今回紹介する事例も、まさに開発中に起こった典型的な問題とその解決策に関するものだ。ウェブサイトが突然動作しなくなり、すべてのページで「500エラー」が表示されるという状況に直面した開発者の経験から、私たちが学べることは多い。

まず、「500エラー」とは、ウェブサイトを閲覧しようとしたときに、そのウェブサイトを提供しているサーバー側で何らかの問題が発生したことを示すエラーコードである。これは、ユーザー側のパソコンやネットワークに問題があるわけではなく、ウェブサイトの裏側で動いているプログラムや設定に異常があることを意味する。今回のケースでは、開発中のNext.jsアプリケーションにおいて、この500エラーが全てのページで表示されるようになった。

同時に表示されたエラーメッセージは、「Module not found: Can't resolve '@vercel/turbopack-next/internal/font/google/font'」というものだった。このメッセージは、「指定されたモジュール、つまり特定のプログラムの部品やファイルが見つからない」ことを意味する。特に、「font/google/font」という部分から、Google Fontsに関連する何らかのファイルが見つからない、という状況が読み取れる。開発者はまず、フォントを配信しているサーバーとのネットワーク接続に問題があるのではないかと疑い、その確認を行ったが、フォントサーバー自体は正常に動作していた。つまり、ネットワークの問題ではなかったのだ。

問題の根本原因は、開発者の作業フローの中にあった。ウェブサイトをNext.jsで開発する際には、主に二つの重要なコマンドを使用する。「next dev」と「next build」である。「next dev」は、開発中にリアルタイムで変更を反映させながらウェブサイトをプレビューするための開発サーバーを起動するコマンドだ。コードを修正するとすぐにブラウザに反映されるため、効率的に開発を進めることができる。一方、「next build」は、開発が終わり、ウェブサイトを実際に公開する準備として、最終的なウェブサイトを構成するすべてのファイルを生成するコマンドである。このコマンドが生成したファイル群が、実際にインターネット上で稼働するウェブサイトの基盤となる。

今回の問題は、この「next dev」が動作している最中に、並行して「next build」コマンドを実行してしまったことに起因していた。Next.jsでは、これらのコマンドが内部的に「.next」という名前の特別なディレクトリを使用する。このディレクトリは、アプリケーションのキャッシュファイル、一時ファイル、そして最終的なビルド成果物など、様々なファイルを保存するために使われる場所だ。いわば、Next.jsが内部で作業を進めるためのワークスペースや、生成された部品を一時的に保管する倉庫のようなものだと考えられる。

「next dev」と「next build」が同じ「.next」ディレクトリに同時に書き込みを行った結果、問題が発生した。それぞれが自身の目的のためにファイルを生成したり、既存のファイルを更新したりする過程で、互いの作業が干渉し合ってしまったのだ。例えるなら、二人の作業員が同じ棚に同時に道具を出し入れしようとして、棚の中身がごちゃ混ぜになり、本来あるべきものがどこにあるかわからなくなってしまったような状態である。これにより、「.next」ディレクトリの中身は正常な状態を保てなくなり、281メガバイトもの混ざり合ったファイル群が生成されてしまった。その結果、Next.jsが内部で使用するビルドシステムが、フォントのインポート情報を管理する仕組みを正常に読み取れなくなり、「フォントが見つからない」というエラーが発生し、最終的に500エラーに繋がったのである。

この問題に対する一時的な解決策は、非常にシンプルだった。破損した「.next」ディレクトリを削除し、新しい、まっさらなディレクトリで開発サーバーを再起動したところ、エラーは解消され、ウェブサイトは正常に動作するようになった。これは、ごちゃ混ぜになった倉庫を一度空っぽにして、必要なものを最初から入れ直すことで、問題が解決したのと同じ理屈だ。しかし、毎回このような問題が発生するたびにディレクトリを削除してやり直すのは、非常に手間がかかり、効率的ではない。これはあくまで一時的な対処療法であり、根本的な解決とは言えなかった。

そこで、開発者はこの問題の根本原因である「衝突」を回避するための恒久的な解決策を考案した。その方法は、「用途ごとに異なるディレクトリを使用する」ことである。具体的には、Next.jsの設定ファイルである「next.config.mjs」を修正する。このファイルは、Next.jsアプリケーション全体の挙動をカスタマイズするための設定を記述する場所だ。ここに「distDir」というオプションを追加する。「distDir」は、ビルドの出力先やキャッシュの場所を指定するための設定項目である。

設定は次のように記述する。 const nextConfig = { distDir: process.env.NEXT_DIST_DIR || ".next", }; これにより、「distDir」の値は、環境変数「NEXT_DIST_DIR」が設定されていればその値を使用し、設定されていなければデフォルトの「.next」を使用するように指示される。

次に、package.jsonファイル内のscriptsセクションを修正する。package.jsonは、プロジェクトの情報や、よく使うコマンドをエイリアスとして登録しておくファイルだ。 "dev": "NEXT_DIST_DIR=.next-dev next dev --turbopack" このように「dev」コマンドを定義することで、「next dev」を実行する際には、環境変数「NEXT_DIST_DIR」が「.next-dev」という値に設定される。つまり、開発サーバーは「.next-dev」というディレクトリをキャッシュや一時ファイルの保存先として使用するようになる。一方、「next build」コマンドは特に環境変数を指定しない限り、デフォルトの「.next」ディレクトリを使用し続ける。

この変更により、開発サーバーが使用するディレクトリと、ビルドプロセスが使用するディレクトリが明確に分離された。開発サーバーは「.next-dev」を使い、ビルドコマンドは「.next」を使うため、両者が同時に実行されても、互いのファイルに干渉することがなくなり、衝突によるファイルの破損を防ぐことができるようになったのだ。さらに、必要であれば、例えば品質保証のための特別なビルドを実行する際に、「NEXT_DIST_DIR=.next-verify next build」のように、別のディレクトリを指定することも可能になる。

最後に、これらの新しいディレクトリ（.next-dev、.next-verifyなど）は、Gitなどのバージョン管理システムに含めるべきではない。これらのディレクトリには、マシン固有の一時ファイルやビルド成果物が含まれており、チームメンバー間で共有する必要がないからだ。そのため、.gitignoreファイルにこれらのディレクトリ名を追加し、誤ってリポジトリにコミットされるのを防ぐことが重要となる。

今回の事例は、一見すると複雑なエラーに見えるが、その原因はシンプルに「リソースの衝突」という問題に帰着した。そしてその解決策は、それぞれの用途に応じてリソースを分離するという、ソフトウェア開発における基本的な設計原則に従うものだった。システムエンジニアを目指す初心者にとって、このような具体的な問題解決の経験は、開発環境のセットアップやトラブルシューティングの重要性を理解する上で非常に役立つだろう。開発プロセスを安定させ、効率的に進めるためには、使用するツールや環境の挙動を深く理解し、適切に設定することが不可欠なのである。