插件依赖

插件依赖是你的插件所依赖的另一个插件，例如你调用其 MCP 服务器或技能的插件。每个依赖都会跟踪其市场提供的最新版本，除非你声明版本约束，即你已测试过的语义版本范围，如 ^2.0 或 ~2.1.0。本页面适用于在 plugin.json 中声明依赖的插件作者和标记发布的市场维护者。

以下情况在其他页面中介绍：

安装具有依赖的插件：请参阅管理已安装的插件
阅读依赖错误：请参阅依赖错误
声明你的插件自身代码所需的 npm 和 Bun 包：请参阅 Node.js 包依赖

要添加约束，请从使用版本约束声明依赖开始。如果你维护其他人依赖的插件，请标记你的发布以便他们的约束可以解析。

声明依赖

如果没有版本约束，依赖会在用户下次更新时移动到其市场发布的每个新版本。如果该版本重命名了你的 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" 以在另一个市场中解析它。使用裸字符串，你的 plugin 依赖于该 plugin 市场提供的任何版本。要设置版本约束，请使用具有这些字段的对象，每个字段都是字符串：

字段	描述
`name`	依赖的 plugin 名称，如其市场条目中所示。Claude Code 在与声明 plugin 相同的市场中查找它，除非你设置 `marketplace`。必需。
`version`	一个语义版本范围，如 `~2.1.0`、`^2.0`、`>=1.4` 或 `=2.1.0`。依赖安装在满足此范围的最高 git 标签处，因此依赖的维护者必须标记发布版本。
`marketplace`	用于解析 `name` 的不同市场。允许列表控制跨市场依赖，详见依赖来自另一个市场的 plugin。

范围不匹配预发布版本，如 2.0.0-beta.1，除非你选择使用预发布后缀，如 ^2.0.0-0。

为团队捆绑 plugin

要让工程师用一个命令安装精选的 plugin 集合，请发布一个清单包含 name 和 dependencies 数组的 plugin。Plugin 清单只需要 name，所以这是一个有效的 plugin，安装它会安装每个依赖。例如，平台团队可以在内部市场中发布特定角色的捆绑包，以便工程师运行一个 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 版本，包含额外的依赖。当市场不默认自动更新时，工程师要么为市场打开自动更新，要么手动更新：

为市场打开自动更新：下一次自动更新会将捆绑包移动到新版本并安装它添加的任何依赖。
手动更新：在 shell 中运行 claude plugin update backend-standard，然后在打开的会话中运行 /reload-plugins 以安装新添加的依赖。

有关工程师端的步骤，请参阅保持 plugin 更新。要将捆绑包部署给组织中的每个人，管理员将其添加到托管设置中的 enabledPlugins。请参阅预安装和要求 plugin。

依赖来自另一个市场的 plugin

默认情况下，Claude Code 不会从与声明 plugin 自身不同的市场安装依赖，除非用户已经在同一范围内安装并启用了该依赖。此默认值防止一个市场从用户未审查的源中静默安装 plugin。要允许安装，请将目标市场的名称添加到根市场的 marketplace.json 中的 allowCrossMarketplaceDependenciesOn。根市场是托管用户正在安装的 plugin 的市场。仅根市场的允许列表适用。以下 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 缺失或不包含目标市场，Claude Code 不会安装依赖。当依赖在市场条目中声明时，安装本身会被拒绝，消息以

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 的依赖条目，所以你不需要从其市场安装依赖。

不需要 version：依赖的本地 plugin.json 也不需要 version，因为版本约束不会针对本地副本进行检查。
命名市场的条目：命名市场的条目在 Claude Code v2.1.242 或更高版本上也匹配本地副本。

在你从其市场安装依赖之前，每当本地副本被禁用或不存在时，你的 plugin 都会停止加载：

你禁用了本地副本：你的 plugin 在下一次 plugin 加载时被禁用，错误以 is disabled — enable it or remove the dependency 结尾。当错误将依赖命名为 <name>@inline 时，该标识符指的是 --plugin-dir 副本。
你启动了一个没有依赖的 --plugin-dir 标志的会话：错误报告依赖未安装。再次传递标志，或从其市场安装依赖。

当两个 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：市场存储库，所以市场维护者创建标签

创建发布标签

将每个发布标记为 <plugin-name>--v<version>，其中 <version> 与该提交的 plugin.json 中的 version 字段匹配。plugin-name 前缀让一个市场存储库可以托管多个具有独立版本历史的 plugin。从 plugin 目录创建标签，配置 origin 远程以接收推送的标签，使用 claude plugin tag：

claude plugin tag --push

该命令从 plugin 的清单构建标签名称。在创建标签之前，它运行这些检查：

验证 plugin
检查 plugin.json 和市场条目在版本上是否一致，当 plugin 目录在市场检出内时
要求 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 和市场条目中的版本同步。

约束具有非 git 源的依赖

基于标签的解析仅适用于 git 支持的源。对于具有 npm、archive 或 command plugin 源的依赖，约束不控制获取哪个版本。它在 plugin 加载时仍会被检查，如果安装的版本不满足它，依赖的 plugin 会被禁用。对于 npm、archive 和 command 源，检查的版本是依赖的 plugin.json 中的 version。在约束该依赖之前在那里设置一个，因为不设置版本的 plugin.json 不满足任何约束。 Claude Code 永远不会自己安装具有 command 源的依赖，所以用户首先安装它。它也永远不会运行依赖的 headersHelper，所以用户也在安装你的 plugin 之前安装其市场条目设置的依赖。除了 claude plugin install，这些操作也会安装任何缺失的声明依赖，command 和 headersHelper 限制也适用于它们：

/reload-plugins
依赖 plugin 市场的自动更新
在依赖 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 的存储库上。当没有标签满足范围时，安装要么失败，要么使用市场的当前副本：

具有自身存储库的 plugin：安装失败，消息包含 Dependency "secrets-vault@your-marketplace" has no git tag satisfying。
由相对路径引用的 plugin：安装改为使用市场的当前副本，约束在 plugin 加载时被检查。如果该副本在范围之外，依赖的 plugin 保持禁用，claude plugin list 显示 Requires "secrets-vault@your-marketplace" ~2.1.0, installed 3.0.0。

对于市场通过相对路径引用的 plugin，你添加为本地文件夹路径的市场也会针对该文件夹的 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 标签处获取受约束的依赖，而不是在市场的最新版本处。如果已安装 plugin 的范围不重叠，自动更新将该依赖保持在其当前版本，/plugin Errors 标签页显示命名约束 plugin 的条目。如果它们重叠但没有标签落在范围内，自动更新获取市场的当前副本，当该副本的 version 落在任何已安装 plugin 范围之外时跳过更新。当用户卸载最后一个约束依赖的 plugin 时，依赖不再被约束到版本范围，并在下一次更新时恢复跟踪其市场条目。

另请参阅

claude plugin prune：删除任何 plugin 不再需要的自动安装依赖
托管市场：发布渠道和推荐其他 plugin

插件

使用插件

创建插件

运行 marketplace

管理组织的插件

故障排除

参考

声明依赖

使用版本约束声明依赖

为团队捆绑 plugin

依赖来自另一个市场的 plugin

在本地测试 plugin 及其依赖

发布其他人依赖的 plugin

创建发布标签

约束具有非 git 源的依赖

依赖如何为你的用户表现

约束如何针对标签进行解析

确认解析的版本

组合来自多个 plugin 的约束

另请参阅

​声明依赖

​使用版本约束声明依赖

​为团队捆绑 plugin

​依赖来自另一个市场的 plugin

​在本地测试 plugin 及其依赖

​发布其他人依赖的 plugin

​创建发布标签

​约束具有非 git 源的依赖

​依赖如何为你的用户表现

​约束如何针对标签进行解析

​确认解析的版本

​组合来自多个 plugin 的约束

​另请参阅

声明依赖

使用版本约束声明依赖

为团队捆绑 plugin

依赖来自另一个市场的 plugin

在本地测试 plugin 及其依赖

发布其他人依赖的 plugin

创建发布标签

约束具有非 git 源的依赖

依赖如何为你的用户表现

约束如何针对标签进行解析

确认解析的版本

组合来自多个 plugin 的约束

另请参阅