Vercelのビルド環境で特定のnpmバージョンを指定する2つの方法
リテールアプリ共創部のるおんです。
VercelでNext.jsアプリをデプロイする際に、 特定のnpmバージョン を使用したい場面がありました。今回は、Vercelのビルド環境で特定のnpmバージョンを指定する2つの方法を実際に試してみたので、その手順と結果をまとめます。
先に結論
Vercelで特定のnpmバージョンを指定する方法は主に2つあります。
方法1: Install Commandのオーバーライド
- Vercelダッシュボードの「Build & Development Settings」でInstall Commandを
npx npm@11.3.0 installなどに変更
方法2: Corepackの使用
- 環境変数
ENABLE_EXPERIMENTAL_COREPACK=1を設定 package.jsonに"packageManager": "npm@11.3.0"を追加
今回は二つの方法を検証して紹介しますが、最終的に自分はpackage.jsonで管理できる方法2をプロジェクトに取り入れました。
前提・やりたいこと
- Next.jsアプリをVercelでデプロイしている
- 特定のnpmバージョン（今回はnpm 11.3.0）を使用したい
- ビルド環境（CICD上）で確実に指定バージョンを使いたい
方法1: Install Commandのオーバーライド
手順
- Vercelダッシュボードにアクセスし、対象プロジェクトの Settings > General に移動
- Build & Development Settings セクションまでスクロール
- Install Command の Override トグルを有効化
- コマンド入力欄に以下を入力して保存
npx npm@11.3.0 install
動作確認
設定後、新しいデプロイを実行してビルドログを確認します。
ビルドログの例
Running build in Washington, D.C., USA (East) – iad1
Build machine configuration: 4 cores, 8 GB
Cloning github.com/ryuhei202/Hapio (Branch: feature/276-upgrade-nextjs-v16-enable-mcp-server, Commit: 7d0f261)
Skipping build cache, deployment was triggered without cache.
Cloning completed: 944.000ms
Running "vercel build"
Vercel CLI 48.8.2
+Running "install" command: `npx npm@11.3.0 install`...
+npm warn exec The following package was not found and will be installed: npm@11.3.0
added 971 packages, and audited 972 packages in 27s
206 packages are looking for funding
run `npm fund` for details
ビルドログで指定したnpmバージョンが使用されていることが確認できました。
また、今回の方法（npx npm@X.X.X install）を使用する場合、指定したnpmバージョンが初回ダウンロードされるため、通常のインストールより若干時間がかかります。実際に指定バージョンのnpmのインストールに約30秒（18:35:59 → 18:36:30） かかっている事がわかります。
メリット・デメリット
メリット
- 設定が簡単で、すぐに適用可能
- Vercelダッシュボードから直接変更できる
デメリット
- Vercelダッシュボードでしか管理できない
- コードリポジトリで管理されないため、変更履歴が追いにくく、チームメンバーが設定を把握しづらい
- 指定npmバージョンのインストールに時間を要する
方法2: Corepackの使用
Corepackは、Node.jsに同梱されているパッケージマネージャーのバージョン管理ツールです。Vercelでは実験的機能として利用可能です。
手順
① 環境変数の設定
Vercelダッシュボードで環境変数を追加します。
- Vercelダッシュボード > 対象プロジェクト > Settings > Environment Variables に移動
- 以下の環境変数を追加
| Name | Value |
|---|---|
ENABLE_EXPERIMENTAL_COREPACK |
1 |
② package.jsonの編集
プロジェクトのルートにあるpackage.jsonにpackageManagerフィールドを追加します。
{
"name": "sample",
"version": "0.1.0",
"private": true,
+ "packageManager": "npm@11.3.0",
"scripts": {
"dev": "next dev --turbopack",
"scan": "next dev --turbopack & npx react-scan@latest localhost:3001",
"build": "next build",
"start": "next start",
...
}
}
packageManagerフィールドに使用したいnpmのバージョンを明示的に指定します。
③ 変更をコミット・プッシュ
git add package.json
git commit -m "feat: specify npm version using Corepack"
git push origin main
動作確認
プッシュ後、Vercelで自動的にデプロイが開始されます。ビルドログを確認してみましょう。
実際のビルドログ
Running build in Washington, D.C., USA (East) – iad1
Build machine configuration: 4 cores, 8 GB
Cloning github.com/ryuhei202/Hapio (Branch: feature/276-upgrade-nextjs-v16-enable-mcp-server, Commit: 7d0f261)
Cloning completed: 1.037s
Restored build cache from previous deployment (GKSxgwScWpPZZjzmMpYCx7bXmJ1C)
Running "vercel build"
Vercel CLI 48.8.2
+> Detected ENABLE_EXPERIMENTAL_COREPACK=1 and "npm@11.3.0" in package.json
Running "install" command: `npm install`...
added 78 packages, and audited 972 packages in 6s
206 packages are looking for funding
run `npm fund` for details
指定したnpm 11.3.0が正しく使用されていることが確認できました。また、①のnpxコマンドを使う方法とは違い、Corepackを使用するので指定したバージョンのnpmを使用するために別途時間がかかっていない事がわかります。
メリット・デメリット
メリット
package.jsonでバージョン管理できる- Gitで変更履歴を追跡可能で、コードレビューで変更を確認できる
- チーム全体で同じバージョンを統一しやすい
- ローカル環境でもCorepackを有効化すれば同じバージョンを使用可能
- 指定したバージョンのnpmを使用するために別途時間がかからない
デメリット
- 実験的機能のため、将来的に仕様が変わる可能性がある
- 環境変数の設定が別途必要
おわりに
VercelのCI環境で特定のnpmバージョンを指定する2つの方法を紹介しました。
- 方法1（Install Command）: 手軽だが、ダッシュボードでしか管理できない。
- 方法2（Corepack）:
package.jsonで管理でき、チーム開発に適している
用途に応じて選択できますが、長期的なメンテナンス性やチーム開発を考慮して、今回は自分はCorepackを使用しました。
以上、どなたかの参考になれば幸いです。
参考
