pnpm 不再建議使用 Corepack 安裝

📅 2026年8月14日

pnpmcorepacknodejspackage-manager

pnpm 不再建議透過 Corepack 安裝，主要有兩個原因：Corepack 會替每次 pnpm 指令加上一層 JavaScript shim，而且目前無法安裝改成原生執行檔的 pnpm 12。

今天看到 pnpm 官方在 X 上發了一句話：

Please don't use corepack to install pnpm.

就這樣，句號，沒有解釋。語氣很像維護者剛處理完一輪相關問題，決定先阻止更多人踩進來。

---

Corepack 在 pnpm 前面多放了一層

Corepack 的用途，是根據專案 package.json 裡的 packageManager 欄位，下載並執行指定版本的套件管理器。

例如：

{
  "packageManager": "pnpm@11.15.0"
}

以前用 Corepack 時，每次輸入 pnpm，實際流程大致會是：

pnpm → Node.js → Corepack shim → 真正的 pnpm

根據 pnpm 更新安裝文件時留下的測試紀錄，同一台機器執行 pnpm 11.21.0，經過 Corepack 約需 264ms，直接執行則是 237ms。

這點時間在本機很難感覺出來，但 CI 可能連續呼叫很多次 pnpm。更重要的是，pnpm 12 已經是原生執行檔，測試中的啟動時間只有約 4ms，前面再啟動一次 Node.js 跑 shim，等於把原生化換來的啟動優勢又吃了回去。

pnpm 12 的套件結構也讓 Corepack 裝不起來

pnpm 12 改寫成原生執行檔後，npm 套件裡不再提供 Corepack 預期的 bin/pnpm.mjs。Corepack 仍依照舊的 JavaScript 入口尋找檔案，結果就是無法安裝 pnpm 12。

pnpm 官方在 2026 年 8 月更新文件時，已經把 Corepack 從安裝頁與 CI 範例移除。官方 PR寫得很直接：現有 CI 範例只能固定在 pnpm@latest-11，升級到下一個 major 時還是得重寫，不如現在就改用 pnpm 自己的安裝方式。

還有一個大環境的變化。Corepack 只隨 Node.js 14.19 到 24 發布（見 Corepack README），Node.js 25 起不再內建。之後若要先用 npm 安裝 Corepack，再由 Corepack 安裝 pnpm，整條路線就繞得有點遠了。

現在怎麼安裝 pnpm？

macOS 與 Linux 可以使用 standalone script：

curl -fsSL https://get.pnpm.io/install.sh | sh -

如果系統已經有 Node.js，也可以直接用 npx 執行官方 installer：

npx get-pnpm

macOS 使用者想交給 Homebrew 管理也可以：

brew install pnpm

GitHub Actions 則使用官方的 pnpm/setup。其他 CI 平台目前都建議使用 standalone script，細節可以直接參考 pnpm 的 CI 文件。

直接安裝 pnpm 之後，packageManager 欄位仍然有效。pnpm 會在第一次執行時切換到專案指定的版本，因此不需要在 CI 設定和 package.json 各維護一次版本號。

已經在用 Corepack，需要立刻換嗎？

如果專案目前使用 pnpm 10 或 11，Corepack 也正常運作，暫時沒有緊急拆掉的必要。這次改變比較像是給新環境的預設建議。真正需要現在動手的，是準備升級 pnpm 12 的專案。

我自己的做法會是：舊專案不為了這句推文立刻改 CI，新專案直接照目前的安裝文件走。等舊專案要升級 pnpm major、Node.js 或重整 pipeline 時，再順手把 Corepack 移除。

至於 2025 年曾經發生的 Corepack 簽章過期問題，那是另一回事，跟這次的建議無關。