適合:用 pnpm 或 npm 的開發者、維護 monorepo 的團隊
pnpm 與 npm 套件排錯
一升級 pnpm 設定就失效、CI 裝套件又出錯、monorepo 找不到自己的套件?這個專題整理最常遇到的安裝問題,從升級、lockfile、monorepo 到發布套件的安全設定,照錯誤訊息就能找到對應的解法。
升級 pnpm 後設定失效?
新版常搬動設定的位置,先確認專案實際用的是哪一版。
- 1. 把設定搬到 pnpm-workspace.yaml
pnpm v11 的 overrides 失效?把 package.json 設定搬到 pnpm-workspace.yaml
升級 pnpm v11 後,package.json 裡的 overrides 或 patchedDependencies 不再生效?本文說明 pnpm 設定位置的變更,示範搬到 pnpm-workspace.yaml,並用 lockfile、pnpm config 與 CI 驗證安全修補沒有悄悄失效。
- 2. 從 RC 升到 pnpm 12 正式版
pnpm 12 穩定嗎?從 RC lockfile 驗證到正式版升級
pnpm 12.0.0 已在 2026 年 8 月 26 日正式發布,帶來 Git 依賴 canonical HTTPS、workspace 設定錯誤檢查與 deterministic lockfile。本文整理從 RC 升級到正式版的相容性驗證、CI pin、回退與常見 lockfile 風險。
- 3. 固定專案使用的 pnpm 版本
pnpm init --init-package-manager 怎麼固定版本?11.25.0 會改看 latest
pnpm 11.25.0 與 12.0.0 的 pnpm init --init-package-manager 會查 registry 的 latest 來決定專案 pin,可能和目前執行中的 pnpm 不同。本文說明 devEngines.packageManager、pnpm-lock.yaml、workspace root、離線 fallback 與 --no-init-package-manager,幫你排查版本看似突然變動的原因。
- 4. 排查 packageManager shim 的 SyntaxError
pnpm 12.3.0 出現 SyntaxError 怎麼修?先查 packageManager shim
專案指定 pnpm 12.3.0 或 12.3.1 時,舊版 pnpm 可能在啟動 native shim 直接報 SyntaxError。本文用版本、PATH、packageManager 與 Corepack 檢查流程定位問題,並說明修補版與安全升級邊界。
安裝失敗,錯誤代碼看不懂?
先讀懂錯誤在說什麼,再決定是更新 lockfile、改設定,還是處理檔案系統的限制。
- 5. 對齊過期的 lockfile
pnpm frozen lockfile 錯誤怎麼修?先對齊 lockfile 與版本
遇到 `ERR_PNPM_FROZEN_LOCKFILE_WITH_OUTDATED_LOCKFILE` 時,不要刪除 pnpm-lock.yaml。本文用 manifest、pnpm pin、devEngines 與相容性資料庫定位原因,整理 pnpm 11.24 與 12 RC 10 的修正、CI 驗證與回退步驟。
- 6. 處理套件完整性檢查失敗
pnpm ERR_PNPM_TARBALL_INTEGRITY 怎麼修?先驗證 lockfile 再更新 checksum
pnpm 安裝時遇到 ERR_PNPM_TARBALL_INTEGRITY,不要先刪 node_modules。本文整理 pnpm 10.34/11.4 的完整性檢查、update-checksums 使用時機、CI 驗證與 lockfile 安全排查。
- 7. 允許需要的 build script
pnpm ERR_PNPM_IGNORED_BUILDS 怎麼修?allowBuilds 與全域安裝
pnpm 遇到 ERR_PNPM_IGNORED_BUILDS,先分辨專案安裝、pnpm dlx 或全域安裝,再選對 allowBuilds 或 --allow-build。本文整理 pnpm v11 的命令版本界線、套件審查與乾淨 CI 驗證。
- 8. 清掉空的代理設定
pnpm ERR_PNPM_INVALID_PROXY 怎麼修?先清掉空的代理設定
pnpm 出現 ERR_PNPM_INVALID_PROXY 且錯誤值是空字串時,問題通常在 HTTP_PROXY、HTTPS_PROXY 或 pnpm-workspace.yaml 的代理設定。本文整理安全清除、有效 URL、pnpm 12 修正版本與 CI 驗證流程。
- 9. 排查受限檔案系統的安裝錯誤
pnpm install 出現 Operation not permitted?先查 hardlink 與 clone
pnpm install 在 rootless container、EdenFS 或受限檔案系統出現 Operation not permitted 時,不一定是套件權限錯誤。本文用 pnpm 12.4.1 的 fallback 行為拆解 packageImportMethod、Docker 跨裝置與安全排錯。
- 10. 處理 script 裡的環境變數展開
pnpm 12 shellEmulator 不展開 ${VAR}?環境變數排錯
pnpm 12 啟用 shellEmulator 時,${VAR} 與 ${VAR:-fallback} 可能原樣傳入 script。本文整理 issue 的重現差異、關閉模擬器的取捨、替代寫法與 CI 驗證步驟。
monorepo 怎麼管、怎麼部署?
先讓 workspace 找得到每個套件,再把要上線的 app 單獨打包。
- 11. 用 npm Workspaces 建立 monorepo
npm Workspaces 入門:用 Vue 3 整理多專案共用程式碼
手上有多個 Vue 3 專案,卻反覆複製元件與設定?這篇用 npm Workspaces 建立 monorepo,示範共用套件、依賴管理、指定 app 指令,以及用 GitHub Actions 從根目錄安裝、建置並部署單一 Vue 系統。
- 12. 對齊套件名稱與 workspace glob
ERR_PNPM_WORKSPACE_PKG_NOT_FOUND 怎麼修?先對齊套件名稱與 workspace glob
pnpm 出現 ERR_PNPM_WORKSPACE_PKG_NOT_FOUND 時,資料夾存在也不代表能被解析。本文依序檢查 pnpm-workspace.yaml、package.json 的 name、workspace: 協定與執行根目錄,避免用錯誤版本掩蓋 monorepo 問題。
- 13. 讓 CI 正確安裝 GitHub 依賴
pnpm 11.21.0 修了 GitHub 依賴 CI 的 publickey 錯誤:升級前後怎麼驗證
pnpm 11.21.0 修正 GitHub shorthand dependency 在沒有 SSH key 的 CI runner 上誤走 SSH 的問題。本文整理 github:owner/repo、git+https 與 git+ssh 的差異,並提供 lockfile 與 CI 驗證順序。
- 14. 把單一 app 裝成 production image
pnpm deploy 怎麼做?把 monorepo 的單一 app 裝成 production image
pnpm monorepo 部署時不必把整個 workspace 帶進 production image。本文用 pnpm deploy、--filter 與 --prod 產生可攜式目錄,說明 injected workspace、Docker multi-stage、files 與 ignore 規則。
怎麼避免裝到惡意套件?
剛發布的版本晚幾天再用,發布帳號的 2FA 和權限也要設好。
- 15. 用 minimumReleaseAge 與 trustPolicy 把關
pnpm 供應鏈安全怎麼設?用 minimumReleaseAge 與 trustPolicy 驗證 lockfile
pnpm v11 已提供 minimumReleaseAge 與 trustPolicy 來延遲新版本、阻擋信任度下降。本文用 pnpm-workspace.yaml 設定、CI 驗證與例外清單,整理 lockfile 供應鏈防護邊界。
- 16. 改用 Trusted Publishing 發布
npm Bypass 2FA 變了怎麼辦?用 Trusted Publishing 或 stage-only token
npm 的 stage-only token 讓 CI 可用 npm stage publish 送審、不能直接 npm publish。本文更新 Bypass 2FA、Trusted Publishing、CLI/Node 版本與 read-only token 的遷移邊界,協助你拆分發佈與安裝權限。
- 17. 處理 72 小時的發布暫停
npm recovery code 登入後不能 publish?先查 72 小時安全暫停
npm 使用 recovery code 登入後,帳號會進入 72 小時安全暫停,期間仍可安裝套件卻不能 publish 或建立 token。本文整理可做與不可做的操作、計時起點、異常排查與恢復後驗證。