理解 Node.js 中的 Peer Dependency：初學者指南

在 Node.js 生態系統中，Peer Dependency（同等依賴）是一個關鍵但容易被誤解的概念。

許多開發者初次接觸時，可能會對其與一般依賴的不同感到困惑。

然而，理解 Peer Dependency 的運作方式，對於開發穩定、可維護且可擴展的應用程式和套件至關重要。

本文將詳細介紹 Peer Dependency 的概念、用途、與其他依賴的差異，以及如何正確使用它。

什麼是 Peer Dependency？

在 Node.js 生態系統中，Peer Dependency（同等依賴） 是一種特殊的依賴管理方式，主要用於確保多個模組共享相同的依賴版本，避免因版本不匹配而導致應用程式運行錯誤。

與一般的 dependencies（必要依賴）不同，Peer Dependency 不會自動安裝，而是要求使用者的專案提供對應版本的依賴。

Peer Dependency 的運作原理

當一個 npm 套件聲明某個 peerDependencies 時，它並不會直接安裝這些依賴，而是將這項責任交給最終使用者。

例如，假設我們開發了一個名為 my-plugin 的 npm 套件，它依賴於 react，但我們不希望它強制安裝自己的 react 版本，而是希望使用者自己提供相容的 react 版本。

在 package.json 中，我們可以這樣定義 peerDependencies：

{
  "name": "my-plugin",
  "version": "1.0.0",
  "peerDependencies": {
    "react": ">=17.0.0"
  }
}

這段設定的意思是：

「我的 my-plugin 需要 react，但請使用者自行安裝 react，且版本至少要是 17.0.0 或更新。」

如果使用者的專案沒有安裝符合條件的 react 版本，npm 會顯示警告，提醒使用者安裝對應的 react。

與一般依賴的區別

在 npm 的 package.json 檔案中，通常會看到三種類型的依賴：

具體範例：dependencies vs peerDependencies

假設我們的 my-plugin 需要 react，如果我們將它放入 dependencies，則 my-plugin 會自動安裝 react：

{
  "name": "my-plugin",
  "version": "1.0.0",
  "dependencies": {
    "react": "^18.0.0"
  }
}

這樣做的問題是，如果使用者的專案已經安裝了 react@17.0.0，但 my-plugin 又安裝了 react@18.0.0，可能會導致應用程式內有兩個不同版本的 react，進而引發錯誤。

例如，在 React 應用中，這可能導致 React Context 無法正常共享狀態，因為不同的 react 實例彼此不兼容。

這時候，使用 peerDependencies 會是更好的選擇：

{
  "name": "my-plugin",
  "version": "1.0.0",
  "peerDependencies": {
    "react": ">=17.0.0"
  }
}

這樣 my-plugin 不會安裝自己的 react，而是要求使用者提供相容的 react 版本。這樣可以確保 my-plugin 與專案中的 react 版本一致，避免版本衝突的問題。

使用 Peer Dependency 的注意事項

• 不會自動安裝：當 npm 解析 peerDependencies 時，不會自動下載這些依賴，而是只會顯示警告，提醒使用者自行安裝。
• 使用 npm ls 檢查安裝狀況：如果不確定某個 peerDependencies 是否已被安裝，可以使用 npm ls [套件名稱] 來檢查，例如： npm ls react 如果 react 版本不符合 peerDependencies 的要求，npm 會顯示錯誤或警告。
• 與 optionalDependencies 不同：peerDependencies 是強制要求使用者安裝相容的依賴，而 optionalDependencies 則表示該依賴是可選的，即使沒有安裝也不會影響專案的運作。

為什麼需要 Peer Dependency？

避免版本衝突

當不同的模組依賴於相同的套件時，如果它們的版本不一致，可能會導致難以預測的行為。

例如，假設一個專案使用 react@17.0.0，而 my-plugin 內部使用 react@18.0.0，這可能會導致 React Hook 無法正常運作，甚至應用程式崩潰。

透過 peerDependencies，我們可以確保 react 只會存在單一版本，減少相容性問題。

保持套件的靈活性

對於像 React、Vue 或 Angular 這類框架，許多插件和工具都需要與這些框架的特定版本相容。

例如，一個 Vue 插件可能需要 Vue 3，但開發者不希望強制用戶安裝 Vue 3，而是希望用戶根據自己的需求選擇 Vue 版本。

因此，這類插件通常會將 Vue 設為 peerDependencies，讓最終使用者自己決定安裝哪個版本。

減少冗餘的安裝

假設你的專案已經安裝了 lodash@4.17.21，但某個外掛卻在 dependencies 中包含了 lodash@4.17.20，這樣 node_modules 目錄中就會有兩個不同版本的 lodash，浪費儲存空間並可能導致函式庫不一致的問題。

使用 peerDependencies，可以確保所有模組共享同一個 lodash 版本，提升專案的效能與穩定性。

如何正確使用 Peer Dependency？

在 package.json 中定義 peerDependencies

如果你正在開發一個需要依賴特定框架的 npm 套件，例如 my-plugin 需要 react，你可以在 package.json 中這樣定義：

{
  "peerDependencies": {
    "react": ">=17.0.0"
  }
}

這表示：任何使用 my-plugin 的人，都必須自行安裝 react，且版本需為 17.0.0 或更新。

安裝 Peer Dependency

當一個專案依賴的某個模組使用 peerDependencies，我們需要手動安裝對應的依賴。例如，如果我們使用 my-plugin，且它要求 react >= 17.0.0，則我們需要這樣安裝：

npm install react

或使用 yarn：

yarn add react

如果沒有安裝對應的 peerDependencies，npm 會顯示警告，例如：

npm WARN my-plugin@1.0.0 requires a peer of react@>=17.0.0 but none is installed.

這提醒開發者需要手動安裝對應的依賴。

在 package.json 中定義 peerDependenciesMeta（可選）

如果你的 peerDependencies 是可選的（例如某些功能才需要），可以使用 peerDependenciesMeta 來標記它們為「非必需」：

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

這樣如果使用者沒有安裝 webpack，npm 仍會發出警告，但不會阻止安裝你的模組。

總結

Peer Dependency 是 Node.js 生態系統中一個關鍵的概念，它允許不同的模組共享相同版本的依賴，避免版本衝突，並減少冗餘安裝。

初學者應該了解它與 dependencies 和 devDependencies 的區別，並學會如何在 package.json 中正確使用它。

當你開發 npm 套件或插件時，如果你的套件需要使用者提供特定的依賴，請務必使用 peerDependencies 來確保相容性。

這不僅能讓你的套件更靈活，也能幫助最終使用者避免因版本問題導致的錯誤。

希望這篇文章能幫助你更好地理解 peerDependencies，並在實際開發中靈活應用！ 🚀