放置していたCloudflare Pages で npm ci が失敗した場合、ビルドイメージのバージョンを確認しよう
Cloudflare Pagesでnpm ciが失敗する問題の解決策。ビルドイメージv2では古いnpmバージョンが使われており、npm 10で作成したpackage-lockと互換性がない。ビルドイメージをv3に更新して解決しよう。
目次
久々にデモアプリを更新した際に、ビルドエラーが発生する問題がありました。ビルドの設定を更新する必要があったので、簡単にまとめます。
npm ciが成功しなくなる
Cloudflare Pages のビルドで以下のエラーが発生しました。
npm error `npm ci` can only install packages when your package.json
and package-lock.json are in sync.
npm error Missing: [email protected] from lock file
npm error Missing: [email protected] from lock file
混乱したのが、ローカル環境では npm ci が成功する点です。何度試しても、Cloudflare Pages にビルドだけ失敗するケースがありました。
原因はビルドイメージ
ビルドイメージv2とnpmバージョンの不一致でした。このPJの設定は以下のようになっていました。
- ローカル環境：Node.js 22.13.0 + npm 10.9.2
- Cloudflare Pages v2：Node.js 22.16.0 + npm 9.6.7（固定）
Cursor x Cloudflare MCPで調査させたところ、v2ビルドイメージは内部的に古いnpmバージョン（9系）を使用する様子です。そのためnpm 10で生成されたpackage-lock.jsonとの互換性がありませんでした。
ビルドログの冒頭をチェックすると、以下のように記録されている場合があります。このケースではビルドイメージが古いと判断しましょう。
Using v2 root directory strategy ← v2が使われている
Detected the following tools from environment: [email protected], [email protected]
ビルドイメージをv3に更新する
対策はシンプルで、ビルドイメージを更新しましょう。
- Cloudflare Pagesダッシュボード
- プロジェクトを選択
- Settings > Builds & deployments
- Build system version を v3 に変更
v3に変更すると Node.js 22 + npm 10.x が正しく使用されるようになります。
もしバージョンが更新できない場合
何かしらの理由で変更できない場合は、package-lock.jsなどを生成する側のnpmバージョンを変えましょう。あまりお勧めはしませんが、とりあえず目の前のビルドを通す目的であればやむを得ないかなと思います。
既存ビルドの「Retry deployment」は設定変更を反映しない
設定変更後にハマったのが、再ビルドは成功しないということです。Cloudflare Pagesでは、既存ビルドの再実行 = そのビルドが作成された時点の設定を使用という仕様らしいです。そのため、v2からv3に変更した後、古いビルドを「Retry」してもv2設定のままビルドされてしまいます。よって手間ではありますが、新しいコミットをpushして、新規ビルドをトリガーしてやりましょう。
参考
- Cloudflare Pages Build Image Documentation
- v2ビルドイメージは2027年2月に廃止予定