pnpm v11 的 overrides 失效？把 package.json 設定搬到 pnpm-workspace.yaml

Q: pnpm v11 還會讀 package.json 的 pnpm 欄位嗎？

不會。pnpm 官方 package.json 文件寫明，v11 起不再讀取該欄位；把設定移到 workspace root 的 pnpm-workspace.yaml，再重新解析和檢查 lockfile。

Q: overrides 可以只放在某個 workspace package 嗎？

pnpm 的 overrides 是 root-only 設定。若只希望某個套件使用不同依賴，先確認是否應該改該套件自己的 dependency 宣告，或使用 pnpm 文件提供的其他 dependency resolution 設定，不要把 root override 複製到子套件。

2026-08-09

DevOps

pnpm

/

/

/

/

升級 pnpm v11 後，如果發現 package.json 裡的 pnpm.overrides 或 pnpm.patchedDependencies 沒有效果，先不要把問題歸因於 lockfile。pnpm 官方文件明確說明：從 v11 開始，pnpm 不再讀取 package.json 的 pnpm field；這些設定要放在 pnpm-workspace.yaml。

直接答案是：把依賴解析與安全修補設定從 package.json 移到 workspace root 的 pnpm-workspace.yaml，再檢查 lockfile、依賴樹和 CI 的 frozen install。packageManager 欄位仍是指定 package manager 的 metadata，不等於 pnpm 設定欄位。

先分清楚哪些設定要搬#

舊專案常把 pnpm 設定和套件 metadata 放在同一個 package.json：

1
{
2
  "pnpm": {
3
    "overrides": {
4
      "some-package": "1.2.3"
5
    },
6
    "patchedDependencies": {
7
      "[email protected]": "patches/[email protected]"
8
    }
9
  }
10
}

pnpm v11 要在 workspace root 的 pnpm-workspace.yaml 宣告：

1
packages:
2
  - "apps/*"
3

4
overrides:
5
  some-package: "1.2.3"
6

7
patchedDependencies:
8
  "[email protected]": "patches/[email protected]"

packages 只在 monorepo 需要時保留或調整；單一 root package 也可以沒有這個欄位。overrides 是 root-only 設定，不能放在某個 workspace package 的 package.json 期待只影響自己。patchedDependencies 的欄位則要依 pnpm settings reference 與實際 patch 檔名核對。

安全遷移的五個步驟#

1. 先列出目前真正使用的設定#

在 workspace root 盤點，不要直接刪掉舊欄位：

1
rg -n '"pnpm"|overrides|patchedDependencies|allowBuilds|minimumReleaseAge|trustPolicy' \
2
  package.json pnpm-workspace.yaml packages apps 2>/dev/null

另外確認是否有 .npmrc、全域 pnpm config 或 CI 指令覆寫設定。官方文件指出，.npmrc 主要讀取 authentication 和 registry settings；其他一般 pnpm 設定應放在 pnpm-workspace.yaml 或全域 config.yaml。

2. 只移動設定，不順便升級依賴#

先把 overrides、patchedDependencies 和現有 v11 需要的其他設定逐項移到 workspace root。不要在同一次變更裡加入大量 pnpm update，否則 lockfile 差異會混合「設定位置遷移」與「版本解析變更」。

如果設定中有 registry URL、token 或其他機密，不能直接把 secret 寫進已提交的 pnpm-workspace.yaml。pnpm 文件也提醒，workspace 設定會進版本控制；授權相關內容應留在受信任的 .npmrc 或 CI secret 流程。

3. 重新解析並檢查 lockfile#

先在乾淨的本機工作副本執行安裝，觀察 lockfile 是否只反映預期的 override 或 patch：

1
pnpm install
2
git diff -- package.json pnpm-workspace.yaml pnpm-lock.yaml

不要在還沒看過 diff 前直接用 --frozen-lockfile 當成驗證；它適合在 lockfile 已經正確提交後確認 CI 可重現。若解析結果大幅改變，先停下來檢查 workspace root、pnpm 版本與設定優先順序。

4. 用 pnpm config 和依賴樹驗證#

pnpm config 可讀取 project 與 global configuration。不要把包含 registry credential 的完整輸出寫入公共 CI log；只查看非敏感設定，再檢查實際依賴：

1
pnpm config list
2
pnpm why some-package
3
pnpm list some-package --depth 10

pnpm why 顯示依賴來源，pnpm list 顯示解析結果；兩者都比只看 package.json 的宣告更接近實際安裝狀態。若是安全修補，還要確認 lockfile 內版本真的已避開受影響版本，而不是只看到 override 字串存在。

5. 最後才在 CI 使用 frozen install#

當本機的 lockfile、patch 和測試都確認後，CI 才使用：

1
pnpm install --frozen-lockfile
2
pnpm test

把 pnpm major 版本固定在本機與 CI 相同，並讓 workflow 在 lockfile 或 pnpm-workspace.yaml 變更時重新安裝。若這次遷移是為了處理惡意套件或撤版風險，也要把 alert、pnpm why、測試和 token 檢查記錄在同一筆變更中；可參考 Dependabot malware alert 的處理順序。