pnpm v10→v11アップグレードで踏んだ3つの落とし穴 ─ Docker・CI環境での対処法まとめ
はじめに
pnpm v11がリリースされ、プロジェクトのパッケージマネージャーをv10からアップグレードしました。ローカル環境では比較的スムーズでしたが、DockerビルドとCIパイプラインが盛大に壊れました。
本記事では、実際にハマったポイントと対処法を「やってみた」形式で共有します。正直なところ、pnpm v11の破壊的変更はかなり多く、公式ドキュメントを読んでも見落としやすい罠がいくつかありました。
前提・環境
- pnpm: v10.32.1 → v11（latest）
- Node.js: 24（LTS）
- フレームワーク: Next.js 16
- Docker: node:24-slim ベースイメージ
- CI: GitHub Actions
pnpm v11の主な破壊的変更
アップグレード前に知っておくべき主要な変更点を整理します。
1. postinstallスクリプトがデフォルトでブロックされる
これが最大の罠でした。 v10まではpostinstallスクリプト（ネイティブモジュールのビルドなど）は警告付きで実行されていましたが、v11では明示的に許可しないとエラーになります。
ERR_PNPM_IGNORED_BUILDS The following dependencies have build scripts that are not executed: sharp, unrs-resolver
2. 設定ファイルの場所が変わった
.npmrc に書いていたpnpm固有の設定（hoist-pattern, node-linker, save-exact など）は、v11では読み込まれません。pnpm-workspace.yaml に移行する必要があります。
| 設定の種類 | v10 | v11 |
|---|---|---|
| レジストリ・認証 | .npmrc |
.npmrc（変更なし） |
| pnpm固有設定 | .npmrc |
pnpm-workspace.yaml |
package.json#pnpm |
読み込まれる | 無視される |
3. 環境変数のプレフィックスが変わった
npm_config_* → pnpm_config_* に変更。CI環境やDockerfileで npm_config_* を使っている場合は要修正。
4. Node.js 22以上が必須
Node.js 18〜21のサポートが切られました。
実際にハマった3つの落とし穴
落とし穴1: allowBuilds でpostinstallスクリプトを許可する
pnpm install を実行すると、sharp（画像処理）や unrs-resolver（ESLint用）など、ネイティブビルドが必要なパッケージでエラーが出ます。
対処法: pnpm-workspace.yaml に allowBuilds を追加します。
# frontend/pnpm-workspace.yaml
allowBuilds:
sharp: true
unrs-resolver: true
プロジェクトルートにも別のパッケージ用に必要でした:
# pnpm-workspace.yaml（ルート）
allowBuilds:
cpu-features: true
ssh2: true
ポイント: どのパッケージが引っかかるかは pnpm install のエラーメッセージを見ればわかります。エラーに表示されたパッケージ名を allowBuilds に追加していけばOKです。
v10までの onlyBuiltDependencies / neverBuiltDependencies / ignoredBuiltDependencies は廃止されているので、既にこれらを使っている場合は allowBuilds に書き換える必要があります。
落とし穴2: Dockerfileで pnpm-workspace.yaml をCOPYし忘れる
pnpm-workspace.yaml は v11 で必須の設定ファイルになりました。しかし、既存のDockerfileでは package.json と pnpm-lock.yaml しかCOPYしていませんでした。
Before（壊れる）:
COPY frontend/package.json frontend/pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
After（動く）:
COPY frontend/package.json frontend/pnpm-lock.yaml frontend/pnpm-workspace.yaml ./
RUN pnpm install --frozen-lockfile
pnpm-workspace.yaml がないと allowBuilds の設定が読み込まれず、postinstallスクリプトがブロックされてDockerビルドが失敗します。
落とし穴3: Docker内で ENV CI=true が必要
上記2つを修正しても、Docker内の pnpm install がまだ失敗するケースがありました。
原因は、pnpm v11が未許可のpostinstallスクリプトを検出したとき、対話的に許可するかどうかをプロンプトで聞いてくる仕様になったことです。Dockerビルド中はTTYがないので、このプロンプトがハングまたはエラーになります。
対処法: ENV CI=true を設定すると、pnpmは非対話モードになり、プロンプトを出さずに allowBuilds の設定に従って動作します。
FROM node:24-slim
ENV CI=true
RUN corepack enable && corepack prepare pnpm@latest --activate
WORKDIR /app
COPY frontend/package.json frontend/pnpm-lock.yaml frontend/pnpm-workspace.yaml ./
RUN pnpm install --frozen-lockfile
ENV CI=true の1行を足すだけですが、これがないとDockerビルドが黙って止まるため、原因の特定に時間がかかりました。
CI（GitHub Actions）の修正
GitHub Actionsでは pnpm/action-setup のバージョン指定も更新が必要でした。
# Before
- uses: pnpm/action-setup@v4
with:
version: 10
# After
- uses: pnpm/action-setup@v4
with:
version: latest
GitHub Actions環境では CI=true がデフォルトで設定されているため、Docker内のような追加対処は不要でした。ただし、pnpm-workspace.yaml が正しくリポジトリにコミットされていないと、CI上でも同じ ERR_PNPM_IGNORED_BUILDS エラーが出ます。
正直な感想
pnpm v11のアップグレードは、率直に言ってめんどくさかったです。
良い点:
allowBuildsによるpostinstallスクリプトの明示的許可は、サプライチェーン攻撃への防御としてセキュリティ面では正しい方向性minimumReleaseAge（公開から24時間未満のパッケージを解決しない）のデフォルト有効化も同様に良い判断- 設定が
pnpm-workspace.yamlに一元化されるのは長期的にはわかりやすい
辛い点:
- 「警告→エラー」の変更はユーザーにとって最もインパクトが大きい破壊的変更で、特にCI/Dockerのような非対話環境で初めて気づく
pnpm-workspace.yamlをDockerfileにCOPYする必要があることは、公式ドキュメントのDocker向けガイドでもっと目立つように書いてほしかったENV CI=trueが必要なことはどこにも明記されておらず、試行錯誤で発見するしかなかった- 破壊的変更の数が多すぎて、公式マイグレーションガイドを読んでも全部を一度に把握するのは難しい
結局のところ、pnpm v11はセキュリティファーストの設計思想への大きな転換です。allowBuilds のデフォルト拒否、minimumReleaseAge、blockExoticSubdeps など、どれも「安全側に倒す」変更です。方向性は正しいと思いますが、移行コストはそれなりにあります。
アップグレード手順のまとめ
pnpx codemod run pnpm-v10-to-v11を実行して機械的な設定移行を行うpnpm installを実行してERR_PNPM_IGNORED_BUILDSエラーに出るパッケージ名を確認pnpm-workspace.yamlにallowBuildsを追加- Dockerfile に
pnpm-workspace.yamlのCOPYを追加 - Dockerfile に
ENV CI=trueを追加 - CI設定（GitHub Actions等）のpnpmバージョンを更新
.npmrcのpnpm固有設定をpnpm-workspace.yamlに移行- lockfileを再生成（
pnpm installで自動更新）
