插件依赖

插件依赖是你的插件所依赖的另一个插件，比如它调用其 MCP 服务器或 skill 的那个。每个依赖默认跟踪其市场提供的最新版本，除非你声明版本约束，即你已测试过的语义化版本范围（如 ^2.0 或 ~2.1.0）。本页面向在 plugin.json 里声明依赖的插件作者和给版本打标签的市场维护者。安装有依赖的插件、读依赖错误、以及声明插件自身代码需要的 npm 和 Bun 包，见其他页面。

声明依赖

没有版本约束时，依赖在用户下次更新时会移动到其市场发布的每个新版本；如果某个新版本重命名了你的插件调用的 MCP 工具，你的插件会对每个更新的人都坏掉。对来自 git 来源的依赖加 ~2.1.0 这样的约束后，已安装你插件的用户继续收到该依赖的 2.1.x 补丁，不会升到 2.2；要按自己的节奏升级，先针对较新版本测试，再发布放宽了约束的新版本。

在插件的 .claude-plugin/plugin.json 的 dependencies 数组里列出依赖。下面的清单声明了一个无版本的依赖和一个有约束的依赖：

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

条目可以是字符串：仅插件名（如 "audit-logger"），或用 "name@marketplace" 在另一个市场里解析；用裸字符串时，你的插件依赖该插件市场提供的任何版本。要设置版本约束，用带这些字段的对象（都是字符串）：

范围不匹配 2.0.0-beta.1 这样的预发布版本，除非你用 ^2.0.0-0 这样的预发布后缀选择加入。

为团队打包插件

要让工程师用一条命令安装一组精选插件，发布一个清单里有 name 和 dependencies 数组的插件。插件清单只需要 name，所以这是一个有效的插件，安装它就会安装每个依赖。例如平台团队可以在内部市场里发布按角色划分的套装，工程师运行一次 claude plugin install 而不是逐个安装：

{
  "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"
  ]
}

之后要往标准集里加插件，发布一个多了依赖的新版本 backend-standard。市场默认不自动更新时，工程师要么为该市场打开自动更新（下次自动更新会把套装移到新版本并安装它新增的依赖），要么手动更新：在 shell 里运行 claude plugin update backend-standard，再在打开的会话里 /reload-plugins 来安装新增的依赖。要给组织里所有人部署一个套装，管理员把它加进托管设置的 enabledPlugins。

依赖另一个市场的插件

默认情况下，Claude Code 不会从与声明插件自己不同的市场安装依赖，除非用户已在同一范围安装并启用了该依赖。这个默认防止一个市场悄悄安装用户没有信任的来源的插件。要允许安装，把目标市场的名字加入根市场 marketplace.json 里的 allowCrossMarketplaceDependenciesOn（根市场是托管用户正在安装的插件的那个，只有根市场的允许列表生效）：

{
  "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 缺失或不含目标市场时，Claude Code 不安装该依赖；依赖声明在市场条目里时，安装本身会被拒绝。允许列表检查不适用于已经启用的依赖：如果用户先自己在同一范围从 your-shared-marketplace 安装了 audit-logger，deploy-kit 之后无需改允许列表就能安装。

本地测试插件及其依赖

如果你同时开发插件和它依赖的插件，从 shell 启动 Claude Code 并用 --plugin-dir 加载两者：

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

依赖的本地副本满足你插件的依赖条目，所以不需要从市场安装依赖。本地的 plugin.json 也不需要 version，因为版本约束不会对本地副本检查；点名了市场的条目在 Claude Code v2.1.242 或更高版本上也匹配本地副本。在你从市场安装该依赖之前，只要本地副本被禁用或缺失，你的插件就会停止加载：你禁用了本地副本，插件在下次加载时被禁用，错误以 is disabled — enable it or remove the dependency 结尾（错误里依赖叫 <name>@inline 时，指的就是 --plugin-dir 副本）；你启动会话时没带依赖的 --plugin-dir 标志，错误报告依赖未安装，重新传标志或从市场安装。两个插件在同一个父文件夹里时，可以只把那个文件夹传给 --plugin-dir 一次，文件夹本身不是插件时，Claude Code 会加载每个含 .claude-plugin/plugin.json 的子文件夹（需要 v2.1.265 或更高）。

发布被他人依赖的插件

如果你维护的插件被其他插件用版本约束依赖，给你的发布打标签，让他们的约束能解析。约束针对托管该插件的仓库上的 git 标签解析，要给插件在 marketplace.json 里的 source 所指向的仓库打标签：github、url 或 git-subdir 来源是插件自己的仓库（由插件作者创建标签）；相对路径（如 ./plugins/secrets-vault）是市场仓库（由市场维护者创建标签）。

创建发布标签

每个发布按 <plugin-name>--v<version> 打标签，其中 <version> 与那个提交里 plugin.json 的 version 字段一致；插件名前缀让一个市场仓库可以托管多个版本历史相互独立的插件。在插件目录里，用配置了 origin 远程的 claude plugin tag 创建标签：

claude plugin tag --push

命令从插件清单构建标签名，创建标签之前先检查：验证插件；插件目录在市场检出里时，检查 plugin.json 和市场条目对版本达成一致；要求插件目录下的工作树干净；标签已存在则拒绝。成功时打印 Created tag secrets-vault--v2.1.0，带 --push 还会打印 Pushed to origin，不带则打印要你自己运行的 git push 命令。传 --dry-run 只看计划而不创建任何东西。你也可以直接运行 git tag secrets-vault--v2.1.0，只要自己保持 plugin.json 和市场条目里的 version 同步。

约束非 git 来源的依赖

基于标签的解析只适用于 git 来源。对 npm、archive 或 command 来源的依赖，约束不控制取哪个版本；它仍会在插件加载时检查，已安装的版本不满足时依赖方插件被禁用。对这些来源，检查的版本是依赖的 plugin.json 里的 version，所以在约束它之前要在那里设一个，因为没设版本的 plugin.json 不满足任何约束。Claude Code 从不自己安装 command 来源的依赖，所以用户要先安装它；它也从不运行依赖的 headersHelper，所以市场条目设置了它的依赖也要用户在安装你的插件之前先装。除 claude plugin install 外，这些操作也会安装任何缺失的已声明依赖，command 和 headersHelper 的限制同样适用：/reload-plugins、依赖方插件所在市场的自动更新、对依赖方插件重新运行 claude plugin install、claude plugin marketplace add。

依赖对用户的行为

约束如何对标签解析：用户安装声明了 { "name": "secrets-vault", "version": "~2.1.0" } 的插件时，依赖从托管 secrets-vault 的仓库上满足 ~2.1.0 的最高 secrets-vault--v 标签安装。没有标签满足范围时：有自己仓库的插件安装失败，消息含 Dependency "secrets-vault@your-marketplace" has no git tag satisfying；通过相对路径引用的插件则使用市场当前的副本，约束在插件加载时检查，如果那个副本在范围之外，依赖方插件保持禁用，claude plugin list 显示它的 Requires ... 说明。对按相对路径引用的插件，作为本地文件夹路径添加的市场在文件夹是 git 仓库时，也针对该文件夹的 git 标签解析约束（需 v2.1.196 或更高版本）。

确认解析出的版本：在 shell 里运行 claude plugin list；按标签解析的依赖显示带 12 位提交后缀的版本，如 2.1.0-8713c5b11005。约束检查用的是标签的版本，而不是 plugin.json 里的 version，即使那个提交里的 plugin.json 落后。如果你强制把标签移到另一个提交，下次安装会获取那个提交的内容而不是复用过期的缓存副本。

合并多个插件的约束：多个已安装插件约束同一个依赖时，依赖解析为满足它们所有范围的最高版本：

自动更新以满足每个已安装插件范围的最高 git 标签获取被约束的依赖，而不是市场的最新版本；已安装插件的范围不重叠时，自动更新让该依赖保持当前版本，并在 /plugin 的 Errors 标签页显示。用户卸载最后一个约束某依赖的插件后，该依赖不再受版本范围约束，下次更新时恢复跟踪它的市场条目。另见：claude plugin prune（移除不再被任何插件需要的自动安装依赖）、「托管市场」（发布渠道和推荐其他插件）。