跳轉到主要內容
一個 plugin 可以通過在 plugin.json 或其 marketplace 條目中列出其他 plugin 來依賴它們。預設情況下，依賴會追蹤最新可用版本，因此上游版本發佈可能會在沒有警告的情況下更改您 plugin 的依賴。版本約束讓您可以將依賴保持在經過測試的版本範圍內，直到您選擇升級。 當您安裝聲明依賴的 plugin 時，Claude Code 會自動解析並安裝它們，並在安裝輸出的末尾列出已添加的依賴。如果依賴後來遺失，/reload-plugins 和背景 plugin 自動更新會重新安裝它，前提是其 marketplace 已在您設定的 marketplace 中。重新執行 claude plugin install 在依賴的 plugin 上，或使用 claude plugin marketplace add 新增 marketplace，也會解析任何未解決的遺失依賴。來自您尚未新增的 marketplace 的依賴將保持未解決狀態。 本指南適用於在 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 欄位匹配。從 plugin 目錄中，執行： 
claude plugin tag --push
claude plugin tag 命令從 plugin 的清單和封閉的 marketplace 項目衍生標籤名稱。在建立標籤之前，它驗證 plugin 內容，檢查 plugin.json 和 marketplace 項目在版本上是否一致，要求 plugin 目錄下的工作樹乾淨，如果標籤已存在則拒絕。添加 --dry-run 以查看將被標記的內容而不建立它。如果您自己保持 plugin.json 和 marketplace 項目同步，直接執行 git tag 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 將被禁用，並出現列出可用版本的錯誤。 已解析標籤的 semver 與 plugin.json 的 version 分開記錄，因此約束檢查使用實際獲取的標籤，即使該提交的 plugin.json 有過時的值。標籤解析安裝的快取目錄名稱包含 12 字元的提交 SHA 後綴，因此如果維護者強制移動標籤到不同的提交，下次安裝會獲得新的快取目錄，而不是重複使用過時的內容。
對於 npm marketplace 來源，約束不控制獲取的版本，因為基於標籤的解析僅適用於 git 支援的來源。約束仍在載入時檢查，如果已安裝的版本不滿足它，依賴 plugin 將被禁用，並出現 dependency-version-unsatisfied 錯誤。

​
約束如何相互作用

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

​
啟用或禁用具有依賴的 plugin

啟用 plugin 也會啟用它所依賴的 plugins，禁用 plugin 如果另一個已啟用的 plugin 仍然需要它則會被阻止。這兩種行為都需要 Claude Code v2.1.143 或更新版本。較早的版本只會啟用或禁用命名的 plugin，並在下次載入時出現 dependency-unsatisfied 錯誤。 當您啟用 plugin 時，Claude Code 也會在相同的範圍內啟用其依賴。如果依賴有其自己的依賴，Claude Code 也會啟用那些。成功訊息會列出隨著您命名的 plugin 一起啟用的其他內容。如果依賴無法啟用，命令會拒絕並告訴您什麼在阻止以及如何修復：
條件結果
依賴未安裝啟用失敗並為每個遺失的依賴列印 claude plugin install 命令。
依賴被您組織的 plugin 政策阻止啟用失敗並命名被阻止的依賴。
依賴在優先級高於目標範圍的範圍內設置為 false啟用失敗。在該範圍內啟用依賴，或傳遞 --scope 以在那裡寫入。
所有依賴都已安裝且被允許啟用成功並為 plugin 和每個在目標範圍內尚未啟用的依賴寫入 true。
這甚至在依賴在其 manifest 中設置 defaultEnabled: false 時也成立，因為 Claude Code 為其寫入明確的 true。同樣的情況也適用於安裝：為滿足活躍 plugin 而引入的依賴會安裝 true，無論其自己的預設值如何。 當您禁用 plugin 時，Claude Code 拒絕如果另一個已啟用的 plugin 仍然依賴它。錯誤命名依賴它的 plugins 並給您一個鏈接命令，以正確的順序禁用它們，以您要求的那個結尾。 例如，如果 deploy-kit 依賴 secrets-vault，單獨禁用 secrets-vault 失敗，輸出類似於以下內容： 
secrets-vault is still required by deploy-kit. Disable that plugin first, or
disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools
從錯誤複製鏈接命令以在一個步驟中禁用完整集合。

​
移除孤立的自動安裝依賴

自動安裝的依賴在安裝它們的 plugins 被卸載後仍會保留在磁碟上，以防您重新安裝依賴 plugin 或想要直接繼續使用依賴。若要清理它們，請執行 claude plugin prune 以列出不再有任何已安裝 plugin 需要的自動安裝依賴，並在確認提示後移除它們。這需要 Claude Code v2.1.121 或更新版本。 
claude plugin prune
預設情況下，prune 在用戶範圍內運作。使用 --scope project 或 --scope local 來針對不同的範圍。傳遞 --dry-run 以列出將被移除的內容而不更改任何內容。傳遞 -y 以跳過確認提示。當 stdin 或 stdout 不是終端時，prune 會列出孤立項並退出，除非傳遞了 -y。 若要在卸載時進行 prune，請將 --prune 傳遞給 claude plugin uninstall。移除命名的 plugin 後，Claude Code 會掃描並移除現在孤立的任何自動安裝依賴。您自己安裝的 plugins 永遠不會被 prune，只有通過另一個 plugin 的 dependencies 陣列自動安裝的 plugins 才會被 prune。 例如，若要卸載 deploy-kit 並清理它留下的依賴： 
claude plugin uninstall deploy-kit --prune

​
解析依賴錯誤

依賴問題會在 claude plugin list、/plugin 介面和 /doctor 中出現。受影響的 plugin 將被禁用，直到您解析錯誤。最常見的錯誤及其修復方法列在下表中。
錯誤含義如何解析
dependency-unsatisfied聲明的依賴未安裝，或已安裝但被禁用。執行錯誤訊息中顯示的 claude plugin install 命令。如果依賴的 marketplace 尚未配置，請使用 claude plugin marketplace add 添加它，Claude Code 將自動解析依賴。如果依賴被禁用，請啟用它。
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 欄位。

​
另請參閱