「Gatsbyを使ってNetlifyにブログを公開するまで」という記事でまとめているように、Netlifyで運用中のブログがあるのですが、先日ブログ記事を公開しようとすると、NetlifyのDeploysの画面で以下のようなエラーが発生していることに気づきました。

6:54:12 PM: Build ready to start
・
・
6:54:34 PM: Now using node v16.15.1 (npm v8.11.0)
6:54:34 PM: Started restoring cached build plugins
6:54:34 PM: Finished restoring cached build plugins
・
・
6:54:35 PM: Started restoring cached node modules
6:54:35 PM: Finished restoring cached node modules
6:54:36 PM: Installing NPM modules using NPM version 8.11.0
・
・
6:54:40 PM: npm ERR! code ERESOLVE
6:54:40 PM: npm ERR! ERESOLVE could not resolve
・
・
6:54:40 PM: npm ERR! Could not resolve dependency:
6:54:41 PM: Failed during stage 'building site': Build script returned non-zero exit code: 1 (https://ntl.fyi/exit-code-1)
・
・
6:54:40 PM: npm ERR! Fix the upstream dependency conflict, or retry
6:54:40 PM: npm ERR! this command with --force, or --legacy-peer-deps
6:54:40 PM: npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
・
・
6:54:40 PM: npm ERR! Conflicting peer dependency: gatsby@4.16.0
6:54:40 PM: npm ERR! node_modules/gatsby
・
・
6:54:40 PM: Error during NPM install
6:54:40 PM: Build was terminated: Build script returned non-zero exit code: 1
6:54:41 PM: Failing build: Failed to build site
6:54:41 PM: Finished processing build request in 26.158287583s

利用しているnpmのパッケージのバージョンが古いためなのか、デプロイの途中で「Could not resolve dependency」というメッセージが表示されていました。
「Conflicting peer dependency: gatsby@4.16.0」というメッセージから、原因は利用しているgatsbyのバージョンに起因する問題のようだと読み取れます。

さらにログを読み進めると、「Fix the upstream dependency conflict, or retry this command with --force, or --legacy-peer-deps」というアドバイスを見つけました。

メッセージの指示に従い、本来であればgatsbyのバージョンを上げて、関連するパッケージの動作確認を行う必要がありますが、今回はデプロイをすぐに行いたかったので、npmコマンドに「--legacy-peer-deps」を指定する形で切り抜けたいと思います。

ログの中で「Now using node v16.15.1 (npm v8.11.0)」との表記があるので、npmのバージョンはv8系であることがわかります。
v8系のドキュメントから「legacy-peer-deps」に関する記述を探してみると、デフォルト値はFalseになっているので、これをTrueにしてあげることで解決しそうです。

Netlifyでnpmコマンドのオプションを指定するには以下の2つの方法があるので、いずれかの設定を行うことでデプロイが成功するようになります。

Netlifyでnpmコマンドのオプションを指定する方法その1

package.json、package-lock.jsonを配置しているディレクトリと同じ階層に.npmrcファイルを準備して、以下の内容を記述する。

.npmrc

legacy-peer-deps=true

Netlifyでnpmコマンドのオプションを指定する方法その2

Netlifyの Deploys → Deploy settings → Environment の画面で環境変数「NPM_FLAGS」に「--legacy-peer-deps」を設定する。

今回、ログ内のメッセージを読み解く際に、Netlifyフォーラムの検索ページを利用しました。
ログの中にはNetlifyフォーラムの検索ページへのリンクが貼られており、このリンクからフォーラムへ移動して、「--legacy-peer-deps」といったキーワードで検索すると、以下のような投稿が該当したので、とても参考になりました。

フォーラム内では、エラーにまつわる投稿とアドバイスがたくさん溢れていますので、今後、上記以外のエラーに遭遇した際にも利用してみようと思います。

参考URL
- npm v7で`ERESOLVE unable to resolve dependency tree Could not resolve dependency:`
- project毎のnpmコマンドをいい感じにするnpmrc & config達