Workers Builds: package.json の packageManager で npm のバージョンを固定する
Workers Builds（Cloudflare の Git 連携ビルド）が、依存のインストール前に packageManager で指定した npm を入れてから npm install するようになった（2026-10-23）。手元の新しい npm で作った lockfile が、ビルド環境の古い npm で解釈されて差分が出る問題を防げる。
いつ使うか
- ローカルではビルドできるのに、Workers Builds だけ
npm ciが lockfile 不一致で落ちる・依存の解決結果が違う - チームや CI とローカルで npm のメジャーバージョンがずれている
- Yarn / pnpm / Bun を使っていて、そのバージョンもビルドで揃えたい
設定
package.json に正確なバージョンで書く。
json
{
"packageManager": "[email protected]"
}- 同じフィールドで Yarn・pnpm・Bun のバージョンも指定できる（例:
"[email protected]"のように正確な版） - 手元の npm に合わせるなら
npm -vの結果をそのまま書く。Corepack を使っている環境ではローカルもこの値に従う
注意点
- 範囲指定は不可:
npm@^11のような書き方ではなく[email protected]のように正確な版を書く engines.npmは見ない: Workers Builds はバージョン選択にengines.npmを使わない。enginesだけ書いていても固定されないのでpackageManagerを足す- 固定した版は自分で上げない限りそのまま。npm を上げたら lockfile の再生成とあわせて
packageManagerも更新する - 他のビルドツール（Renovate など）が
packageManagerを自動更新する設定になっていないかも確認しておく