案例分享：如何解決 Yarn Peer Dependency 安裝問題（NVM 與 Corepack 的影響）

更新日期： 2025 年 3 月 20 日

在開發專案時，使用 NVM（Node Version Manager） 來切換 Node.js 版本並搭配 Yarn 管理套件，是許多開發者的標準做法。

然而，當環境設定不完全相容時，可能會導致意想不到的錯誤，影響專案的正常運作。

這篇文章將透過我自身的經驗，分享如何排查並解決 Peer Dependency 無法正常安裝 的問題，幫助開發者避免類似的困擾。

問題背景：Yarn 安裝套件時遇到 Peer Dependency 錯誤

某天，我在開發環境中需要使用 Node.js 14.19.0，因此我透過 NVM 切換至這個版本，並使用 Yarn 來管理專案套件。

理論上，這應該是很標準的操作流程，但當我執行：

yarn install

卻發現 Peer Dependency 無法正常安裝，導致某些套件無法順利安裝。

這讓我感到困惑，因為過去在其他環境下並沒有遇到這個問題。

為了進一步排查，我嘗試執行以下指令來確認 Corepack 的狀態：

which corepack

結果顯示：

/home/username/.nvm/versions/node/v14.19.0/bin/corepack

這個結果讓我大吃一驚，因為 Node.js 14.19.0 應該不會預設包含 Corepack。

Corepack 是 Node.js 16.9.0 之後才內建的工具，理論上它不應該出現在我的環境中。

這時我意識到，這個問題可能與 Corepack 的錯誤安裝 有關，進而影響了 Yarn 的正常運作。

問題分析：為什麼 Corepack 會影響 Yarn？

當我遇到 Yarn Peer Dependency 安裝失敗 的問題時，一開始並不清楚根本原因。

但經過深入調查後，我發現問題可能與 Corepack 的錯誤存在 有關，而這與 Node.js 版本的相容性 以及 NVM 環境內的全域模組管理 息息相關。以下是詳細的分析：

Corepack 與 Node.js 版本不匹配

Corepack 是什麼？

Corepack 是 Node.js 內建的一個工具，主要用來 管理封裝 Yarn 和 Pnpm，讓開發者可以直接使用 corepack enable 來啟用這些套件管理工具，而不需要額外安裝。

但這項功能並不是所有 Node.js 版本都支援，它是在 Node.js 16.9.0 之後才正式內建的功能。

為什麼 Corepack 會影響 Yarn？

在我的案例中，我切換到 Node.js 14.19.0，理論上這個版本 不應該內建 Corepack。

但當我執行 which corepack 時，卻發現 Corepack 仍然存在，且路徑顯示它是來自於 NVM 管理的 Node.js 14.19.0 環境。

這代表 Corepack 並非來自系統預設，而是某些情境下被額外安裝的，可能是：

1. 過去使用過較高版本的 Node.js（例如 16.9.0 以上），而當時 Corepack 被啟用，導致它的相關設定殘留。
2. 安裝過 Corepack 作為全域模組，即使後來切換回較舊的 Node.js 版本，它仍然存在。
3. 某些安裝工具（如 Homebrew 或 nvm）曾經安裝 Corepack，但在切換 Node.js 版本後未被正確移除。

由於 Corepack 代理 了 Yarn，它的存在意味著當我執行 yarn install 時，實際上 Yarn 的行為可能受到 Corepack 影響。

當 Yarn 嘗試解析 Peer Dependencies 時，可能因為 Corepack 的干擾，導致 Yarn 無法正確處理相依關係，進而造成 Peer Dependency 無法安裝 的錯誤。

NVM 環境內的全域模組影響

NVM 如何管理 Node.js 版本？

NVM（Node Version Manager）是一個動態切換 Node.js 版本的工具。

它允許我們在不同的專案間使用不同版本的 Node.js，並且會為每個 Node.js 版本維護 獨立的全域模組 安裝目錄。

但在實際運作中，當我們從較新版本的 Node.js（如 16.9.0）切換回舊版本（如 14.19.0）時。

有些全域模組（例如 Corepack）可能 不會自動刪除，這就會導致舊版本的 Node.js 仍然引用這些不相容的模組。

為什麼這會影響 Yarn？

在這個案例中，當我切換到 Node.js 14.19.0 時，NVM 可能仍然保留了之前的 Corepack。這導致：

1. 當我執行 yarn install 時，Yarn 可能不是直接運行，而是被 Corepack 代理後執行。
2. Corepack 可能使用了與 Node.js 14.19.0 不相容的 Yarn 版本，導致 Yarn 無法正確解析 Peer Dependencies。
3. 在某些情境下，Corepack 會影響 Yarn 的安裝邏輯，讓 yarn install 時的行為與原生 Yarn 不一致。

由於 NVM 切換版本時不會自動清理這些遺留模組，因此最直接的解決方案就是 手動刪除 Corepack，確保 Yarn 能夠獨立運行，而不受 Corepack 影響。

解決方法：刪除 Corepack 並重新安裝 Yarn

確定問題的根源後，我決定手動刪除錯誤的 Corepack，然後重新安裝 Yarn。

步驟 1：移除 Corepack

由於 Node.js 14.19.0 不應該包含 Corepack，我直接刪除了它：

rm -rf /home/username/.nvm/versions/node/v14.19.0/lib/node_modules/corepack

這個指令的作用是刪除 Node.js 14.19.0 版本內的 Corepack，避免它影響 Yarn 的正常運作。

步驟 2：重新安裝 Yarn

接著，我重新安裝 Yarn，以確保它能獨立運行，而不會受到 Corepack 的影響。

npm install -g yarn

這樣可以確保 Yarn 使用的是正確的版本，而不會被 Corepack 代理。

步驟 3：重新執行 Yarn 指令

刪除 Corepack 並重新安裝 Yarn 之後，我再次執行：

yarn install

這次一切順利，Peer Dependency 的安裝問題完全解決！

結論

這次的經驗讓我學到了一些重要的事情：

1. 當發生 Yarn 安裝錯誤時，先檢查 Corepack 是否影響了環境
   • 使用 which corepack 指令，確認 Corepack 是否存在，以及它的來源路徑是否正確。
2. Corepack 並非所有 Node.js 版本都適用
   • 只有 Node.js 16.9.0 以上 才內建 Corepack，較低版本如果出現 Corepack，可能是來自舊環境的殘留，應該手動刪除。
3. 使用 NVM 時，記得檢查全域模組的影響
   • NVM 切換 Node.js 版本時，某些全域模組可能會影響新環境的行為，例如 Corepack 可能影響 Yarn 的運作。

這次的錯誤雖然讓我花了一些時間排查，但也讓我更加理解 Yarn、Corepack 以及 NVM 之間的相依關係。

希望這篇案例分享能幫助到有類似問題的開發者！ 🚀