外掛程式相依性

外掛程式相依性是您的外掛程式所依賴的另一個外掛程式，例如您呼叫其 MCP 伺服器或技能的外掛程式。每個相依性會追蹤其市集提供的最新版本，除非您宣告版本約束，即您已測試過的語義版本範圍，例如 ^2.0 或 ~2.1.0。本頁面適用於在 plugin.json 中宣告相依性的外掛程式作者，以及標記發行版本的市集維護者。

這些情況涵蓋在其他頁面上：

安裝具有相依性的外掛程式：請參閱管理已安裝的外掛程式
讀取相依性錯誤：請參閱相依性錯誤
宣告您的外掛程式自身程式碼所需的 npm 和 Bun 套件：請參閱 Node.js 套件相依性

若要新增約束，請從使用版本約束宣告相依性開始。如果您維護其他人依賴的外掛程式，請標記您的發行版本，以便其約束可以解析。

宣告依賴

沒有版本約束的情況下，依賴會在使用者下次更新時移至其 marketplace 發佈的每個新發行版本。如果該發行版本重新命名了你的 plugin 呼叫的 MCP 工具，你的 plugin 會對所有更新的人中斷。使用約束（例如來自 git 支援來源的依賴上的 ~2.1.0），已安裝你的 plugin 的使用者會持續接收依賴的 2.1.x 修補程式，永遠不會移至 2.2。若要按自己的時間表升級，請針對較新的發行版本進行測試，然後發佈你的 plugin 的新版本，其中包含更寬的約束。

使用版本約束宣告依賴

在你的 plugin 的 .claude-plugin/plugin.json 的 dependencies 陣列中列出依賴。以下資訊清單宣告一個未版本化的依賴和一個受約束的依賴：

.claude-plugin/plugin.json

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

一個項目可以是字串：僅 plugin 名稱，例如此資訊清單中的 "audit-logger"，或 "name@marketplace" 以在另一個 marketplace 中解析它。使用裸字串，你的 plugin 依賴於該 plugin 的 marketplace 提供的任何版本。若要設定版本約束，請使用具有這些欄位的物件，每個都是字串：

欄位	說明
`name`	依賴的 plugin 名稱，如其 marketplace 項目中所示。Claude Code 在與宣告 plugin 相同的 marketplace 中查詢它，除非你設定 `marketplace`。必需。
`version`	語義版本範圍，例如 `~2.1.0`、`^2.0`、`>=1.4` 或 `=2.1.0`。依賴會安裝在滿足此範圍的最高 git 標籤，因此依賴的維護者必須標記發行版本。
`marketplace`	用於解析 `name` 的不同 marketplace。允許清單控制跨 marketplace 依賴，詳見依賴來自另一個 marketplace 的 plugin。

範圍不符合預發行版本，例如 2.0.0-beta.1，除非你使用預發行後綴（例如 ^2.0.0-0）選擇加入。

為團隊組合 plugin

若要讓工程師使用一個命令安裝精選的 plugin 集合，請發佈一個資訊清單包含 name 和 dependencies 陣列的 plugin。Plugin 資訊清單只需要 name，所以這是一個有效的 plugin，安裝它會安裝每個依賴。例如，平台團隊可以在內部 marketplace 中發佈角色特定的組合，以便工程師執行一個 claude plugin install 而不是分別安裝每個 plugin：

.claude-plugin/plugin.json

{
  "name": "backend-standard",
  "version": "1.0.0",
  "description": "Standard plugin set for backend engineers",
  "dependencies": [
    "secrets-vault",
    "deploy-kit",
    { "name": "db-migrate", "version": "^3.0" },
    "oncall-runbook"
  ]
}

若要稍後將 plugin 新增至標準集合，請發佈新的 backend-standard 版本，其中包含額外的依賴。當 marketplace 不預設自動更新時，工程師要麼為 marketplace 開啟自動更新，要麼手動更新：

為 marketplace 開啟自動更新：下一次自動更新會將組合移至新版本並安裝它新增的任何依賴。
手動更新：在 shell 中執行 claude plugin update backend-standard，然後在開啟的工作階段中執行 /reload-plugins 以安裝新增的依賴。

有關工程師端的步驟，請參閱保持 plugin 更新。若要將組合部署給組織中的每個人，管理員會將其新增至受管設定中的 enabledPlugins。請參閱預先安裝並要求 plugin。

依賴來自另一個 marketplace 的 plugin

預設情況下，Claude Code 不會從與宣告 plugin 自身不同的 marketplace 安裝依賴，除非使用者已在相同範圍內安裝並啟用該依賴。此預設值可防止一個 marketplace 從使用者未審查的來源無聲地安裝 plugin。若要允許安裝，請將目標 marketplace 的名稱新增至根 marketplace 的 marketplace.json 中的 allowCrossMarketplaceDependenciesOn。根 marketplace 是託管使用者正在安裝的 plugin 的 marketplace。只有根 marketplace 的允許清單適用。以下 marketplace.json 允許 deploy-kit 依賴來自 your-shared-marketplace 的 plugin：

.claude-plugin/marketplace.json

{
  "name": "your-marketplace",
  "owner": { "name": "Your Org" },
  "allowCrossMarketplaceDependenciesOn": ["your-shared-marketplace"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "your-shared-marketplace" }
      ]
    }
  ]
}

如果 allowCrossMarketplaceDependenciesOn 遺失或不包含目標 marketplace，Claude Code 不會安裝依賴。當依賴在 marketplace 項目中宣告時，安裝本身會被拒絕，並顯示以

Dependency "audit-logger@your-shared-marketplace" (required by deploy-kit@your-marketplace) is in marketplace "your-shared-marketplace", which is not in the allowlist

開頭的訊息，並命名要設定的欄位。當它在 plugin.json 中宣告時，安裝完成而不包含依賴，然後你的 plugin 無法載入。允許清單檢查不適用於已啟用的依賴。如果使用者首先在相同範圍內從 your-shared-marketplace 自行安裝 audit-logger，deploy-kit 隨後會安裝而無需對允許清單進行任何變更。

在本機測試 plugin 及其依賴

如果你同時開發 plugin 及其依賴的 plugin，請從 shell 啟動 Claude Code 並使用 --plugin-dir 載入兩者：

claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin

依賴的本機副本滿足你的 plugin 的依賴項目，因此你不需要從其 marketplace 安裝依賴。

不需要 version：本機 plugin.json 也不需要 version，因為版本約束不會針對本機副本進行檢查。
命名 marketplace 的項目：命名 marketplace 的項目也符合 Claude Code v2.1.242 或更新版本上的本機副本。

在你從其 marketplace 安裝依賴之前，每當本機副本被停用或不存在時，你的 plugin 都會停止載入：

你停用了本機副本：你的 plugin 在下一次 plugin 載入時被停用，並顯示以 is disabled — enable it or remove the dependency 結尾的錯誤。當錯誤將依賴命名為 <name>@inline 時，該識別碼指的是 --plugin-dir 副本。
你啟動了沒有依賴的 --plugin-dir 旗標的工作階段：錯誤報告依賴未安裝。再次傳遞旗標，或從其 marketplace 安裝依賴。

當兩個 plugin 都在一個父資料夾中時，你可以一次將該資料夾傳遞給 --plugin-dir。如果資料夾本身不是 plugin，Claude Code 會載入每個具有 .claude-plugin/plugin.json 的子資料夾。需要 Claude Code v2.1.265 或更新版本。

發行其他人依賴的 plugin

如果你維護其他 plugin 使用版本約束依賴的 plugin，請標記其發行版本，以便這些約束可以解析。約束會針對託管 plugin 的儲存庫上的 git 標籤進行解析。標記 plugin 的 plugin 來源在 marketplace.json 中指向的儲存庫：

github、url 或 git-subdir 來源：plugin 自身的儲存庫，因此 plugin 的作者建立標籤
相對路徑，例如 ./plugins/secrets-vault：marketplace 儲存庫，因此 marketplace 維護者建立標籤

建立發行標籤

將每個發行版本標記為 <plugin-name>--v<version>，其中 <version> 符合該提交的 plugin.json 中的 version 欄位。plugin-name 前綴讓一個 marketplace 儲存庫可以託管多個具有獨立版本歷史的 plugin。從 plugin 目錄建立標籤，並配置 origin 遠端以接收推送的標籤，使用 claude plugin tag：

claude plugin tag --push

該命令從 plugin 的資訊清單建立標籤名稱。在建立標籤之前，它執行這些檢查：

驗證 plugin
當 plugin 目錄在 marketplace 簽出內時，檢查 plugin.json 和 marketplace 項目是否同意版本
需要 plugin 目錄下的乾淨工作樹
如果標籤已存在，則拒絕

成功執行會列印 Created tag secrets-vault--v2.1.0。使用 --push，它也會列印 Pushed to origin。沒有 --push，它會列印你自己執行的 git push 命令。傳遞 --dry-run 以查看計畫而不建立任何內容。 claude plugin tag 參考列出其餘旗標。你也可以直接執行 git tag secrets-vault--v2.1.0，只要你自己保持 plugin.json 中的 version 和 marketplace 項目中的版本同步。

約束具有非 git 來源的依賴

標籤型解析僅適用於 git 支援的來源。對於具有 npm、archive 或 command plugin 來源的依賴，約束不控制擷取哪個版本。當 plugin 載入時仍會檢查它，如果已安裝的版本不滿足它，則依賴 plugin 會被停用。對於 npm、archive 和 command 來源，檢查的版本是依賴的 plugin.json 中的 version。在約束該依賴之前在那裡設定一個，因為不設定版本的 plugin.json 不滿足任何約束。 Claude Code 永遠不會自行安裝具有 command 來源的依賴，因此使用者首先安裝它。它也永遠不會執行依賴的 headersHelper，因此使用者也在安裝你的 plugin 之前安裝其 marketplace 項目設定的依賴。除了 claude plugin install 之外，這些操作也會安裝任何遺失的宣告依賴，command 和 headersHelper 限制也適用於它們：

/reload-plugins
依賴 plugin 的 marketplace 自動更新
在依賴 plugin 上重新執行 claude plugin install
claude plugin marketplace add

依賴如何為你的使用者表現

這些部分說明一旦你的 plugin 與其他 plugin 一起安裝，Claude Code 如何解析、檢查和組合你宣告的約束。

約束如何針對標籤進行解析

當使用者安裝宣告 { "name": "secrets-vault", "version": "~2.1.0" } 的 plugin 時，依賴會從滿足 ~2.1.0 的最高 secrets-vault--v 標籤安裝在託管 secrets-vault 的儲存庫上。當沒有標籤滿足範圍時，安裝要麼失敗，要麼使用 marketplace 的目前副本：

具有自身儲存庫的 plugin：安裝失敗，訊息包含 Dependency "secrets-vault@your-marketplace" has no git tag satisfying。
由相對路徑參考的 plugin：安裝改為使用 marketplace 的目前副本，並在 plugin 載入時檢查約束。如果該副本超出範圍，依賴 plugin 保持停用，claude plugin list 顯示 Requires "secrets-vault@your-marketplace" ~2.1.0, installed 3.0.0。

對於 marketplace 由相對路徑參考的 plugin，你新增為本機資料夾路徑的 marketplace 也會針對該資料夾的 git 標籤解析約束，當資料夾是 git 儲存庫時。這需要 Claude Code v2.1.196 或更新版本。不是 git 儲存庫的本機資料夾沒有標籤，因此 Claude Code 改為從資料夾的目前內容安裝依賴。

確認解析的版本

若要確認約束解析到哪個版本，請在 shell 中執行 claude plugin list。標籤解析的依賴會顯示其版本，帶有 12 字元提交後綴，例如 2.1.0-8713c5b11005。約束檢查使用標籤的版本而不是 plugin.json 中的 version，即使該提交的 plugin.json 落後。如果你強制移動標籤到不同的提交，下一次安裝會擷取該提交的內容而不是重複使用陳舊的快取副本。請參閱版本和更新以了解 plugin 的版本如何成為其快取鍵。

組合來自多個 plugin 的約束

當多個已安裝的 plugin 約束相同的依賴時，依賴會解析到滿足所有其範圍的最高版本。常見的組合解析如下：

Plugin A 要求	Plugin B 要求	結果
`^2.0`	`>=2.1`	在最高 `2.x` 標籤處進行一次安裝，位於或高於 `2.1.0`。兩個 plugin 都載入。
`~2.1`	`~3.0`	安裝 plugin B 失敗，並顯示 `has conflicting version requirements` 訊息。Plugin A 和依賴保持原樣。
`=2.1.0`	無	依賴保持在 `2.1.0`。自動更新在安裝 plugin A 時跳過較新的版本。

自動更新會在滿足每個已安裝 plugin 範圍的最高 git 標籤處擷取受約束的依賴，而不是在 marketplace 的最新版本處。如果已安裝 plugin 的範圍不重疊，自動更新會將該依賴保留在其目前版本，/plugin Errors 標籤會顯示命名約束 plugin 的項目。如果它們重疊但沒有標籤落在範圍內，自動更新會擷取 marketplace 的目前副本，並在該副本的 version 落在任何已安裝 plugin 的範圍之外時跳過更新。當使用者卸載最後一個約束依賴的 plugin 時，依賴不再受約束於版本範圍，並在下一次更新時恢復追蹤其 marketplace 項目。

另請參閱

claude plugin prune：移除任何 plugin 不再需要的自動安裝依賴
託管 marketplace：發行通道和推薦其他 plugin

外掛程式

使用外掛程式

建立外掛程式

執行 marketplace

管理您組織的外掛程式

疑難排解

參考資料

宣告依賴

使用版本約束宣告依賴

為團隊組合 plugin

依賴來自另一個 marketplace 的 plugin

在本機測試 plugin 及其依賴

發行其他人依賴的 plugin

建立發行標籤

約束具有非 git 來源的依賴

依賴如何為你的使用者表現

約束如何針對標籤進行解析

確認解析的版本

組合來自多個 plugin 的約束

另請參閱

​宣告依賴

​使用版本約束宣告依賴

​為團隊組合 plugin

​依賴來自另一個 marketplace 的 plugin

​在本機測試 plugin 及其依賴

​發行其他人依賴的 plugin

​建立發行標籤

​約束具有非 git 來源的依賴

​依賴如何為你的使用者表現

​約束如何針對標籤進行解析

​確認解析的版本

​組合來自多個 plugin 的約束

​另請參閱

宣告依賴

使用版本約束宣告依賴

為團隊組合 plugin

依賴來自另一個 marketplace 的 plugin

在本機測試 plugin 及其依賴

發行其他人依賴的 plugin

建立發行標籤

約束具有非 git 來源的依賴

依賴如何為你的使用者表現

約束如何針對標籤進行解析

確認解析的版本

組合來自多個 plugin 的約束

另請參閱