Yarn 如何解決 Node.js Peer Dependency 問題

By徐培鈞
LinkedIn

更新日期： 2025 年 3 月 20 日

本文為 Yarn 套件基礎，第 5 篇：

  1. Yarn 套件管理器完整指南：初學者入門
  2. Corepack 是什麼？完整解析與常見問題解決方案
  3. Yarn Start 與 Yarn Build 的差異與用途
  4. 理解 Node.js 中的 Peer Dependency：初學者指南
  5. Yarn 如何解決 Node.js Peer Dependency 問題　👈進度
  6. 案例分享：如何解決 Yarn Peer Dependency 安裝問題（NVM 與 Corepack 的影響）

在開發 Node.js 應用時，Peer Dependency（對等依賴） 常常讓初學者感到困惑。

當專案內的某些套件需要與其他特定版本的套件共同運行，而這些依賴關係未被正確安裝時，就會導致錯誤或衝突。

本文將詳細解釋 Peer Dependency 的概念、Yarn 如何處理這類依賴問題，並與 npm 進行比較，幫助你更有效地管理專案依賴。

什麼是 Peer Dependency（對等依賴）？

Peer Dependency 是一種類型的依賴關係，它告訴我們某個套件 必須與另一個特定版本的套件一起運行，但不會自動安裝該依賴。

例如，許多前端 UI 框架（如 react）的第三方套件，都需要與特定版本的 react 共同運行：

{
  "peerDependencies": {
    "react": "^18.0.0"
  }
}

這表示該套件需要 React 18 或更新版本，但 不會自動安裝 React，而是由專案的開發者來確保正確的 React 版本已經存在。

為什麼需要 Peer Dependency？

  1. 避免重複安裝不同版本的相同套件：如果 react 相關的插件各自安裝不同版本的 react，可能會導致應用錯誤。
  2. 確保插件與主套件的相容性：例如，某些 react 插件可能只支援 react@18，如果你的專案使用的是 react@17，可能會導致錯誤。
  3. 減少套件體積：Peer Dependency 允許專案共用相同的核心套件，而不是在不同插件內各自安裝一份。

Yarn 如何解決 Peer Dependency 問題？

在開發 Node.js 應用時，Peer Dependency 的管理是一項重要但容易忽視的問題。

Yarn 提供了多種方式來處理 Peer Dependency，以減少錯誤、提高相容性，並提升開發者的體驗。

以下是 Yarn 解決 Peer Dependency 問題的幾種策略：

自動安裝 Peer Dependency（Yarn v2+）

問題：npm 與舊版 Yarn 需要手動安裝 Peer Dependency

在 npm 6 及以下版本，如果套件有 Peer Dependency，npm 只會顯示警告，但不會自動安裝對應的依賴。

例如，某個套件可能要求 react@^18.0.0，但如果你的專案內沒有 react，npm 只會提醒你缺少這個依賴，而不會主動幫你安裝。

這導致開發者在安裝套件後，還需要額外閱讀錯誤訊息，手動補充缺少的 Peer Dependency，增加了開發的複雜度與錯誤機率。

解決方案：Yarn 2+ 自動安裝 Peer Dependency

從 Yarn 2 開始，Yarn 會自動安裝 Peer Dependency，讓開發者不再需要手動處理這類依賴問題，確保相依套件之間的相容性。

範例：使用 Yarn 2 自動安裝 Peer Dependency

假設你的 package.json 內有以下 Peer Dependency：

{
  "peerDependencies": {
    "react": "^18.0.0"
  }
}

在 npm 6（或 Yarn 1）中，你需要手動執行以下指令來補充缺少的 Peer Dependency：

npm install react

但在 Yarn 2+ 中，你只需執行：

yarn install

Yarn 會自動偵測 peerDependencies，並安裝相應的 react 版本，例如 [email protected]。這大幅減少了開發者的負擔，不必再為每個 Peer Dependency 進行額外的安裝操作。

Yarn 的額外優勢：確保單一版本依賴

除了自動安裝 Peer Dependency，Yarn 也能確保專案內的所有套件共用相同版本的 Peer Dependency。

例如，專案內的多個套件都需要 react@18，Yarn 會確保所有套件都使用相同的 react 版本，避免因版本不一致而發生錯誤。

使用 peerDependenciesMeta 避免安裝錯誤（Yarn v2+）

問題：有些 Peer Dependency 是可選的，但 Yarn 會強制報錯

在某些情況下，開發者可能不一定需要安裝某些 Peer Dependency。

例如，某個插件可以與不同的 Webpack 版本搭配使用，但有些專案可能並不需要 Webpack。

如果 Yarn 強制要求安裝 webpack，就會造成不必要的額外依賴。

解決方案：使用 peerDependenciesMeta 來設定可選依賴

Yarn 允許開發者透過 peerDependenciesMeta 標記某些 Peer Dependency 為可選（optional）。

這樣即使這些依賴沒有安裝，Yarn 也不會報錯，而是僅顯示警告，讓開發者自行決定是否需要安裝該依賴。

範例：標記 webpack 為可選 Peer Dependency

假設某個套件可以搭配 Webpack，但 Webpack 並不是必需的，可以在 package.json 內設定如下：

{
  "peerDependencies": {
    "webpack": "^5.0.0"
  },
  "peerDependenciesMeta": {
    "webpack": {
      "optional": true
    }
  }
}

運作方式

  • 如果 webpack 已安裝，則 Yarn 會使用專案內的 Webpack 版本。
  • 如果 webpack 沒有安裝，則 Yarn 不會報錯，但會顯示警告，提醒開發者如果需要 Webpack，應該自行安裝對應版本。

這樣的機制對於開發「可選插件」的套件特別有用，例如 Babel、ESLint、Webpack 等工具的擴充插件，讓開發者可以自行選擇是否要安裝，而不會影響整個專案的相依性。

使用 yarn info 檢查 Peer Dependency

問題：如何確認某個套件的 Peer Dependency？

有時候，你可能想知道某個套件有哪些 Peer Dependency，或者檢查你目前的專案是否已滿足這些依賴關係。

解決方案：使用 yarn info 指令來檢查 Peer Dependency

Yarn 提供 yarn info 指令，可以幫助開發者快速檢查某個套件的 Peer Dependency。

範例：查詢某個套件的 Peer Dependency

假設你想檢查 some-package 這個套件有哪些 Peer Dependency，可以執行：

yarn info some-package peerDependencies

如果 some-package 需要 react@^18.0.0 和 webpack@^5.0.0，那麼你會看到類似以下的輸出：

{
  "react": "^18.0.0",
  "webpack": "^5.0.0"
}

這可以幫助開發者確認哪些 Peer Dependency 需要安裝，以及目前專案是否已滿足這些相依性，避免在運行時發生錯誤。

進階應用：搭配 yarn why 指令

如果你想知道為什麼某個 Peer Dependency 會出現在你的專案中，可以使用：

yarn why react

這會顯示哪些套件依賴於 react，以及它們的版本資訊，讓你可以更清楚專案內的依賴關係。

與 npm 的比較：Yarn 更好用嗎？

在管理 Peer Dependency（對等依賴）時，npm 和 Yarn 採用了不同的策略。

雖然 npm 在 7 版之後引入了自動安裝 Peer Dependency 的功能，但 Yarn 2+ 提供了更靈活的管理機制，使開發者能夠更輕鬆地處理相依性問題。

以下是 npm 與 Yarn 在 Peer Dependency 管理上的比較：

功能npm 6 及以下npm 7+Yarn 1Yarn 2+
自動安裝 Peer Dependency❌ 否✅ 是❌ 否✅ 是
顯示 Peer Dependency 警告✅ 是✅ 是✅ 是✅ 是
可選的 Peer Dependency❌ 否✅ 是（但不同於 Yarn）❌ 否✅ 是
檢查 Peer Dependency✅ 是 (npm ls)✅ 是 (npm ls)✅ 是 (yarn list)✅ 是 (yarn info)

自動安裝 Peer Dependency

  • npm 6 及以下：當遇到 Peer Dependency 時，npm 不會自動安裝，而是只顯示警告，開發者需要手動安裝。
  • npm 7+ 和 Yarn 2+：這兩個版本開始支援自動安裝 Peer Dependency，不再需要手動處理。

但 npm 7+ 和 Yarn 2+ 的機制仍有不同：

  • npm 7+ 自動安裝的方式較為嚴格，可能會造成一些相依性衝突。例如，若某個套件的 Peer Dependency 要求 react@17，但專案中已安裝 react@18，npm 可能會因無法滿足條件而報錯。
  • Yarn 2+ 則採用更靈活的方式，會嘗試解析相依性，確保專案內的所有 Peer Dependency 都能共存，而不會輕易報錯。

✅ 結論：如果你的專案有較多的 Peer Dependency，相比 npm 7+，Yarn 2+ 能更順暢地處理相依性，減少衝突發生的機率。

可選的 Peer Dependency

  • npm 7+：開始支援可選 Peer Dependency，但與 Yarn 不同，npm 會讓這些可選依賴變成**「軟性需求」**（如果可用則安裝）。
  • Yarn 2+：提供了 peerDependenciesMeta，讓開發者更精細地控制哪些 Peer Dependency 是可選的，並決定是否要報錯或只是顯示警告。

舉例比較

假設有一個套件 my-plugin，它的 package.json 如下：

{
  "peerDependencies": {
    "webpack": "^5.0.0"
  }
}

如果你的專案不使用 Webpack，但又需要安裝 my-plugin，那麼：

  • npm 7+：會嘗試安裝 Webpack，即使你不需要它。
  • Yarn 2+：允許開發者在 peerDependenciesMeta 中標記 Webpack 為「可選」，這樣就不會強制安裝 Webpack，但仍會顯示警告提醒開發者。

✅ 結論：Yarn 2+ 提供的 peerDependenciesMeta 更加靈活，讓開發者能夠決定哪些 Peer Dependency 是真正必要的，避免不必要的安裝。

檢查 Peer Dependency

  • npm 提供 npm ls 指令來檢查已安裝的依賴樹，但它的輸出內容較為冗長且不直覺。
  • Yarn 2+ 提供 yarn info，可以直接查看某個套件的 Peer Dependency，輸出結果清晰易讀。

範例比較

在 npm 中執行：

npm ls react

會列出整個依賴樹，有時資訊過多，難以找到關鍵 Peer Dependency。

在 Yarn 2+ 中，執行：

yarn info react peerDependencies

則會直接顯示 Peer Dependency，避免冗長的輸出。

✅ 結論：Yarn 2+ 提供更直覺的工具，讓開發者能快速檢查並解決 Peer Dependency 的問題。

總結與建議

  • 如果你的專案會用到大量 Peer Dependency，建議使用 Yarn 2+，它能自動安裝，減少管理負擔。
  • 若你使用 npm，請確保你的版本是 7 或更新，因為舊版 npm 不會自動安裝 Peer Dependency。
  • 善用 peerDependenciesMeta 來控制可選依賴，避免不必要的錯誤與警告。

Peer Dependency 雖然讓人頭疼，但透過 Yarn 提供的管理機制，你可以更順利地處理這些依賴，確保專案的穩定性與相容性！ 🚀

Similar Posts