Node Corepack でパッケージマネージャを管理する

May 21, 2026 · 3 min read

プロジェクトをクローンした直後に、ローカルの Yarn や pnpm のバージョンがプロジェクトの想定と一致せずエラーが発生した経験があれば、Node Corepack が解決しようとしている問題をすでに理解しているはずです。パッケージマネージャのバージョン管理は、CI や Docker ビルド、あるいはチームメンバーのマシンで何かが壊れるまで見過ごされがちです。

Corepack は、プロジェクト内でパッケージマネージャのバージョンを直接ピン留めし、それを自動的に強制することでこの問題に対処します。本記事では、その仕組み、最近の変更点、そして注意すべきポイントを解説します。

要点

Corepack は、package.json の packageManager フィールドを読み取り、あらゆる環境で正しい Yarn または pnpm のバージョンが使われることを保証するバイナリプロキシです。
Node.js 25 以降、Corepack はバンドルされなくなり、npm install -g corepack で明示的にインストールする必要があります。
CI 設定、Dockerfile、オンボーディングドキュメントを更新し、corepack enable を実行する前に Corepack の明示的なインストール手順を含めましょう。
オフラインまたはエアギャップ環境のビルドでは、ネットワークアクセスが可能なうちに corepack prepare <pm>@<version> --activate でバイナリを事前取得しておきます。
pnpm は、Corepack に全面的に依存せずに自身のパッケージマネージャバージョンを管理する機能もサポートしています。

Node Corepack が実際に行うこと

Corepack は、シェルコマンドとパッケージマネージャのバイナリの間に位置するバイナリプロキシ層です。yarn install や pnpm add を実行すると、Corepack はその呼び出しをインターセプトし、package.json の packageManager フィールドを確認し、正しいバージョンが使われることを保証します。ローカルにキャッシュされていなければ、必要に応じてダウンロードします。

これにより、パッケージマネージャのバージョン管理は、開発者ごとのセットアップ手順ではなく、プロジェクト構成の一部となります。

packageManager フィールドは次のようになります:

{
  "packageManager": "yarn@4.2.2"
}

ハッシュを末尾に付与してダウンロードしたバイナリを検証することもでき、改ざんされたレジストリや侵害されたミラーからの保護に役立ちます。

Node.js 25 以降、Corepack はバンドルされなくなった

オンライン上の多くのセットアップガイドは、Corepack が Node.js に同梱されていることを前提としています。これは Node.js 16.9 から 24 までは正しく、実験的なオプトインツールとして含まれていました。しかし Node.js 25 以降、Corepack は Node.js とともに配布されなくなりました。

実務上の影響は大きく、次のとおりです:

ローカル開発: Node.js 25 以降を使う開発者は、npm install -g corepack で Corepack を明示的にインストールする必要があります。
CI パイプライン: GitHub Actions、GitLab CI などで最近の Node.js イメージを利用している環境では、Corepack がデフォルトで利用できなくなります。ワークフローファイルに明示的なインストール手順が必要です。
Docker コンテナ: Node.js 25 以降をベースにしたイメージには Corepack が含まれません。Dockerfile に RUN npm install -g corepack を追加してください。
オンボーディングドキュメント: 事前のインストール手順なしに「corepack enable を実行してください」と書かれている README やコントリビュートガイドは、新しい Node バージョンを使う新規コントリビュータの環境では機能しなくなります。

インストール後のワークフローは従来と同じです。corepack enable を実行して shim を有効化し、あとは packageManager フィールドに任せましょう。

Yarn と pnpm で Corepack を使う

Yarn と pnpm はどちらも、バージョン固定ワークフローのために Corepack の利用を推奨しています。

Yarn を Corepack でセットアップする場合、フィールドを設定して有効化します:

corepack use yarn@4.2.2
corepack enable

pnpm を Corepack で使う場合も同じパターンです:

corepack use pnpm@10.0.0
corepack enable

Corepack がインストールされ有効化されている場所であれば、ローカルマシン、CI、コンテナのいずれでもピン留めされたバージョンが強制されます。

最近の pnpm リリースでは、pnpm 自体を通じてパッケージマネージャのバージョンを直接管理することもサポートされており、pnpm のみを使う環境では Corepack への依存を減らせます。

オフラインおよびエアギャップ環境

Corepack はパッケージマネージャのバイナリをオンデマンドでダウンロードするため、ネットワークアクセスのない環境では失敗します。解決策は、オフラインになる前にバイナリを事前取得しておくことです:

corepack prepare yarn@4.2.2 --activate

ネットワークアクセスが可能な段階で、Docker イメージのビルド時や CI のセットアップフェーズで実行してください。

まとめ

Node Corepack は、チーム全体でパッケージマネージャのバージョンを強制する最もシンプルな手段のひとつであり続けています。package.json の packageManager フィールドは、依存関係に対する lockfile と同じ再現性の保証を、ツール側にもたらしてくれます。

プロジェクトとドキュメントで更新すべき重要な点は、Corepack がプリインストールされていると仮定しないことです。Node.js 25 以降では明示的なインストールが必要です。誰かが分かりにくいエラーに遭遇して 1 時間デバッグに費やす前に、CI 設定、Dockerfile、コントリビュータガイドに今すぐその手順を追加しましょう。

よくある質問

おそらく不要です。npm は Node.js に同梱されているため、npm のみを使うプロジェクトの多くは、選択した Node.js リリースに含まれる npm バージョンに依存しています。Corepack が最もよく使われるのは、環境をまたいでより厳格にパッケージマネージャのバージョンを固定したい Yarn や pnpm のワークフローです。

Corepack が有効化されていれば、コマンドはインターセプトされ、グローバルにインストールされた Yarn や pnpm を無視して、packageManager に宣言されたバージョンがダウンロード/切り替えされます。Corepack が有効化されていない場合は、グローバルにインストールされたバイナリが実行されるため、まさに Corepack が防ごうとしているバージョンのずれの問題が発生します。

packageManager フィールドにハッシュを付与できます。例えば yarn@4.2.2+sha224.<hash> のようにします。Corepack は実行前にダウンロードしたバイナリをそのハッシュに対して検証します。これにより改ざんされたレジストリや侵害されたミラーから保護でき、サプライチェーンセキュリティ要件が厳しいプロジェクトでは強く推奨されます。

直接はできません。packageManager フィールドはルートの package.json に定義され、原則としてリポジトリ全体に適用されます。Corepack は 1 プロジェクトにつき 1 つのパッケージマネージャを想定しています。ワークスペースごとに本当に異なるツールが必要な場合は、通常、リポジトリを分割するか、Corepack の外側でカスタムのオーケストレーションを行うことになります。

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay. — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.