pnpm ERR_PNPM_TARBALL_INTEGRITY 怎麼修？先驗證 lockfile 再更新 checksum

先分清楚是哪一種 integrity 錯誤#

官方 release notes 也列出例外：git-hosted tarball 和 file: tarball 不走同一套 remote registry integrity 判斷；前者由 commit SHA 錨定，後者由本機路徑控制。不要把所有 tarball 錯誤都套用同一個修法。

第一步：記錄版本與實際來源#

先在出錯的專案根目錄保存環境資訊，不要急著刪 lockfile：

1
pnpm --version
2
node --version
3
pnpm config get registry
4
git status --short

接著確認 package.json 的 packageManager、CI 使用的 pnpm major version，以及本機和 CI 是否指向同一個 registry。pnpm 10.34 和 11.4 的行為不能直接推論到所有舊版本；如果團隊還在使用 pnpm 9 或更早版本，先把版本差異記錄下來，再決定要升級或只做重現。

第二步：定位 lockfile 中的套件#

把錯誤訊息中的套件名稱代入搜尋，不要一開始就重建整份 lockfile：

1
rg -n \
2
  '套件名稱|integrity:' \
3
  pnpm-lock.yaml

要看的不是只有那一行 hash，而是同一個 package 的：

• version 和 resolution URL 是否如預期。
• lockfile 是否在最近的 PR 中被手動修改。
• registry URL 是否從 public registry 變成 mirror 或 private registry。
• 同一套件是否有多個 peer dependency snapshot，導致你查錯位置。

若錯誤只在 CI 發生，將 CI 的 pnpm 版本、registry、proxy 設定和 cache key 與本機逐項對照。不要把「本機可以裝」直接當成 lockfile 正確，因為兩邊可能下載到不同來源。

第三步：只有確認來源可信，才用 --update-checksums#

pnpm 官方提供的明確 opt-in 是：

1
pnpm install --update-checksums

它的用途是依目前 registry 提供的內容刷新 lockfile integrity。這個指令不是「修復任何安裝錯誤」的通用捷徑；執行前至少要確認：

1. registry 是團隊預期的官方或受信任 mirror。
2. proxy 或 cache 沒有把另一個檔案誤當成該套件。
3. 套件版本、resolution URL 和 lockfile 變更來自可審核的來源。
4. 更新後的 pnpm-lock.yaml diff 只包含預期套件。

執行後立即檢查：

1
git diff -- pnpm-lock.yaml
2
pnpm install --frozen-lockfile

如果 hash 改了，但你找不到 registry 或套件內容為什麼改變，先停止，不要把新 hash 當成證據。重新計算 checksum 只能讓目前下載到的 bytes 通過檢查，不能證明它就是團隊原本想要的套件。

哪些指令不會繞過 integrity 保護#

pnpm 10.34／11.4 的 release notes 特別說明，下面幾個行為不能取代完整性驗證：

• pnpm install --force 不會自動覆寫 mismatch。
• pnpm update 不會把鎖定的 integrity 當成可靜默改寫的值。
• pnpm install --fix-lockfile 的用途是補齊 lockfile 結構，不是繞過 hash。
• pnpm install --frozen-lockfile 仍維持原本的 frozen 行為。

這些差異很實用：如果你看到有人在 CI 失敗時直接加 --force，那不等於完成了 supply-chain 排查。先判斷套件版本是否應該更新；若是 registry 內容非預期改變，應保留證據並向 registry 或套件維護者確認。

什麼情況應該更新套件，而不是更新 checksum#

若套件版本被重新發布、mirror 同步了不同內容，或原本的 resolution URL 已不再是團隊信任的來源，優先選擇升到一個新的、可驗證的版本，再提交 package manifest 和 lockfile。不要在沒有解釋的情況下把舊版本重新 hash。

若 lockfile 缺少 integrity，先查它是由哪個 pnpm 版本、哪個 pruner、哪個自動化工具產生。pnpm 11.4 對 remote tarball 缺少 integrity 會 fail closed；直接補值可能掩蓋有人修改 lockfile 的事實。

CI 中的安全落地方式#

建議在 CI 固定三件事：

1. 使用 repository 宣告的 pnpm 版本，而不是 runner 預裝的 latest。
2. 以 pnpm install --frozen-lockfile 進行安裝，讓 lockfile mismatch 直接暴露。
3. 把 pnpm-lock.yaml 的變更放進 PR review，不允許安裝步驟在背景中默默改檔。

如果 CI 使用 private registry 或 mirror，把 registry host、認證範圍和 cache 命中策略一起寫入部署文件。完整性 hash 是檔案內容的檢查點，不是 registry 身份、credentials 或 build script 安全性的替代品。

ZeroOne 既有的 pnpm Git dependency 在 CI 出現 publickey 錯誤時的排查處理的是 Git transport 和 SSH 權限；如果錯誤指向 tarball integrity，應改用本篇的 registry／lockfile 路徑。若你正在從 pnpm 10 遷移到 11，也可以先看 pnpm v11 package.json settings 遷移檢查，把版本升級和 integrity 變更分開驗證。

常見問題#