跳轉到主要內容
一個 plugin 可以通過在 plugin.json 或其 marketplace 條目中列出其他 plugin 來依賴它們。預設情況下，依賴會追蹤最新可用版本，因此上游版本發佈可能會在沒有警告的情況下更改您 plugin 的依賴。版本約束讓您可以將依賴保持在經過測試的版本範圍內，直到您選擇升級。 當您安裝聲明依賴的 plugin 時，Claude Code 會自動解析並安裝它們，並在安裝輸出的末尾列出已添加的依賴。 本指南適用於在 plugin.json 中聲明依賴的 plugin 作者，以及標記版本發佈的 marketplace 維護者。若要安裝具有依賴的 plugin，請參閱發現並安裝 plugin。如需完整的 manifest 架構，請參閱 Plugins 參考。
依賴版本約束需要 Claude Code v2.1.110 或更新版本。

​
為什麼要限制依賴版本

考慮一個內部 marketplace，其中兩個團隊發佈 plugin。平台團隊維護 secrets-vault，這是一個包裝 secrets 後端的 MCP 伺服器。部署團隊維護 deploy-kit，它在部署期間調用 secrets-vault 來獲取認證。 deploy-kit 已針對 secrets-vault v2.1.0 進行測試。沒有版本約束的情況下，下次平台團隊標記重新命名 MCP 工具的版本發佈時，自動更新會將每個工程師的 secrets-vault 移至新版本，deploy-kit 就會損壞。 使用版本約束，deploy-kit 聲明它需要 ~2.1.0 範圍內的 secrets-vault。安裝了 deploy-kit 的工程師會保持在最高匹配的 2.1.x 修補程式版本。部署團隊通過發佈具有更寬鬆約束的新 deploy-kit 版本，按照自己的時間表進行升級。

​
聲明具有版本約束的依賴

在 plugin 的 .claude-plugin/plugin.json 的 dependencies 陣列中列出依賴。每個條目要麼是 plugin 名稱，要麼是具有版本約束的物件。 以下 manifest 聲明了一個未版本化的依賴和一個受約束的依賴：
.claude-plugin/plugin.json
{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}
一個條目可以是只包含 plugin 名稱的純字符串，如上例中的 "audit-logger"，它依賴於該 plugin 的 marketplace 提供的任何版本。為了獲得更多控制，請使用具有以下欄位的物件：
欄位類型描述
namestringPlugin 名稱。在與聲明 plugin 相同的 marketplace 內解析。必需。
versionstring一個 semver 範圍，例如 ~2.1.0、^2.0、>=1.4 或 =2.1.0。依賴會在滿足此範圍的最高標記版本處獲取。
marketplacestring一個不同的 marketplace 來在其中解析 name。跨 marketplace 依賴被阻止，除非目標 marketplace 在根 marketplace 的 marketplace.json 中的 allowCrossMarketplaceDependenciesOn 中列出。
version 欄位接受 Node 的 semver 套件支援的任何表達式，包括 caret、tilde、hyphen 和 comparator 範圍。預發佈版本（如 2.0.0-beta.1）被排除，除非您的範圍使用預發佈後綴（如 ^2.0.0-0）選擇加入。

​
依賴來自另一個 marketplace 的 plugin

預設情況下，Claude Code 拒絕自動安裝位於與聲明它的 plugin 不同的 marketplace 中的依賴。這可防止一個 marketplace 無聲地從您未審查的來源拉入 plugin。 若要允許此操作，根 marketplace 的維護者將目標 marketplace 名稱添加到 marketplace.json 中的 allowCrossMarketplaceDependenciesOn。根 marketplace 是託管用戶正在安裝的 plugin 的 marketplace；只有其允許清單被查詢，因此信任不會通過中間 marketplace 鏈接。 以下 marketplace.json 允許 deploy-kit 依賴來自 acme-shared 的 plugin：
.claude-plugin/marketplace.json
{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "acme-shared" }
      ]
    }
  ]
}
如果欄位缺失或不包含目標 marketplace，安裝將失敗，並出現 cross-marketplace 錯誤，命名要設置的欄位。用戶仍然可以先手動安裝依賴，這會滿足約束而無需更改允許清單。

​
標記 plugin 版本發佈以進行版本解析

版本約束針對 marketplace 儲存庫上的 git 標籤進行解析。為了讓 Claude Code 找到依賴的可用版本，上游 plugin 的版本發佈必須使用特定的命名約定進行標記。 將每個版本發佈標記為 {plugin-name}--v{version}，其中 {version} 與該提交的 plugin.json 中的 version 欄位匹配。 
git tag secrets-vault--v2.1.0
git push origin secrets-vault--v2.1.0
plugin 名稱前綴讓一個 marketplace 儲存庫可以託管多個具有獨立版本線的 plugin。--v 分隔符被解析為完整 plugin 名稱上的前綴匹配，因此包含連字符的 plugin 名稱會被正確處理。 當您安裝聲明 { "name": "secrets-vault", "version": "~2.1.0" } 的 plugin 時，Claude Code 會列出 marketplace 的標籤，篩選以 secrets-vault--v 開頭的標籤，並獲取滿足 ~2.1.0 的最高版本。如果不存在匹配的標籤，依賴 plugin 將被禁用，並出現列出可用版本的錯誤。
對於 npm marketplace 來源，約束不控制獲取的版本，因為基於標籤的解析僅適用於 git 支援的來源。約束仍在載入時檢查，如果已安裝的版本不滿足它，依賴 plugin 將被禁用，並出現 dependency-version-unsatisfied 錯誤。

​
約束如何相互作用

當多個已安裝的 plugin 限制同一依賴時，Claude Code 會交集它們的範圍，並將依賴解析為滿足所有範圍的最高版本。下表顯示常見組合如何解析。
Plugin A 要求Plugin B 要求結果
^2.0>=2.1在最高 2.x 標籤處進行一次安裝，該標籤位於 2.1.0 或更高版本。兩個 plugin 都會載入。
~2.1~3.0Plugin B 的安裝失敗，出現 range-conflict 錯誤。Plugin A 和依賴保持原樣。
=2.1.0無依賴保持在 2.1.0。在安裝了 Plugin A 時，自動更新會跳過較新版本。
自動更新在應用更新之前，針對每個已安裝 plugin 的範圍檢查每個受約束的依賴。如果 marketplace 將依賴移至任何範圍之外的版本，更新將被跳過，跳過訊息會命名限制 plugin。 當您卸載最後一個限制依賴的 plugin 時，依賴不再被保持，並在下次更新時恢復追蹤其 marketplace 條目。

​
解析依賴錯誤

依賴問題會在 claude plugin list、/plugin 介面和 /doctor 中出現。受影響的 plugin 將被禁用，直到您解析錯誤。最常見的錯誤及其修復方法列在下表中。
錯誤含義如何解析
range-conflict依賴的版本要求無法組合。錯誤訊息命名原因：沒有版本滿足所有範圍、範圍不是有效的 semver 語法，或組合的範圍太複雜而無法交集。卸載或更新其中一個衝突的 plugin，修復任何無效的 version 字符串，簡化長 || 鏈，或要求上游作者擴寬其約束。
dependency-version-unsatisfied已安裝的依賴版本在此 plugin 的聲明範圍之外。執行 claude plugin install <dependency>@<marketplace> 以根據所有當前約束重新解析依賴。
no-matching-tag依賴的儲存庫沒有滿足範圍的 {name}--v* 標籤。檢查上游是否使用上述約定標記了版本發佈，或放寬您的範圍。
若要以程式設計方式檢查這些錯誤，請執行 claude plugin list --json 並讀取每個 plugin 上的 errors 欄位。

​
另請參閱