在 Claude Code 中通过 version 字段声明插件依赖的 semver 范围，可以防止上游更新破坏已有插件。核心操作：在 .claude-plugin/plugin.json 的 dependencies 数组里用对象指定 name 和 version（如 "~2.1.0"），并为每个依赖发布 git tag 按 {name}--v{version} 格式命名。跨市场依赖需在根 marketplace.json 中设置 allowCrossMarketplaceDependenciesOn。执行 claude plugin tag --push 自动创建 tag；使用 claude plugin install 或 /reload-plugins 解决依赖。常见错误：no-matching-tag、range-conflict、dependency-version-unsatisfied。

Claude Code 插件依赖版本约束配置指南

一个插件可以依赖其他插件，通过在 plugin.json 或市场条目中列出。默认情况下，依赖追踪最新可用版本，上游发布变更时可能无预警地改变插件下的依赖。版本约束允许你将一个依赖锁定在经过测试的版本范围内，直到你选择升级。

当你安装一个声明了依赖的插件时，Claude Code 会自动解析并安装它们，并在安装输出的末尾列出添加了哪些依赖。如果某个依赖后来丢失了，/reload-plugins 和后台插件自动更新会重新安装它，前提是该依赖的市场已配置在你的市场列表中。在依赖插件上重新运行 claude plugin install，或者通过 claude plugin marketplace add 添加一个市场，也会解析任何未解决的缺失依赖。来自你尚未添加的市场的依赖将保持未解析状态。

本文档面向在 plugin.json 中声明依赖的插件作者，以及发布 tag 的市场维护者。要安装带有依赖的插件，参见 发现和安装插件。完整的清单结构参见 插件参考。

依赖版本约束需要 Claude Code v2.1.110 或更高版本。

为什么要约束依赖版本

考虑一个内部市场，两个团队发布插件。平台团队维护 secrets-vault，一个包装密钥后端的 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 来按自己的节奏升级。

如何声明带版本约束的依赖

在插件 .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	string	插件名称。在声明插件的同一市场中解析。必填。
version	string	semver 范围，例如 ~2.1.0, ^2.0, >=1.4, 或 =2.1.0。依赖将获取满足此范围的最高已标记版本。
marketplace	string	解析 name 的另一个市场。除非目标市场在根市场的 marketplace.json 中的 allowCrossMarketplaceDependenciesOn 字段列出，否则跨市场依赖会被阻止。

version 字段接受 Node 的 semver 包支持的任何表达式，包括 caret、tilde、hyphen 和比较器范围。预发布版本（如 2.0.0-beta.1）会被排除，除非你的范围通过前缀如 ^2.0.0-0 选择加入。

如何跨越市场依赖插件

默认情况下，Claude Code 拒绝自动安装与声明插件不同市场的依赖。这防止了一个市场静默地从你未审查的源中引入插件。

要允许跨市场依赖，根市场（即托管用户正在安装的插件的市场）的维护者需在 marketplace.json 的 allowCrossMarketplaceDependenciesOn 列表中添加目标市场名称。只有根市场的许可列表被检查，因此信任不会通过中间市场传递。

以下 marketplace.json 允许 deploy-kit 依赖来自 acme-shared 的插件：

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "acme-shared" }
      ]
    }
  ]
}

如果该字段缺失或未包含目标市场，安装失败并显示 cross-marketplace 错误，指明需要设置的字段。用户仍可以先手动安装该依赖，这样无需更改许可列表即可满足约束。

为版本解析标记插件发布

版本约束解析依赖于市场仓库中的 git 标签。为了让 Claude Code 找到依赖的可用版本，上游插件的发布必须使用特定的命名约定进行标记。

将每个发布标记为 {插件名称}--v{版本号}，其中 {版本号} 与提交中 plugin.json 的 version 字段一致。在插件目录中运行：

claude plugin tag --push

claude plugin tag 命令从插件清单和所属市场条目中推导出标签名称。在创建标签之前，它会验证插件内容，检查 plugin.json 与市场条目是否版本一致，要求插件目录下工作区干净，并且如果标签已存在则拒绝。添加 --dry-run 可以查看将要标记的内容而不实际创建。如果你自行保持 plugin.json 和市场条目同步，直接运行 git tag secrets-vault--v2.1.0 是等效的。

插件名称前缀允许一个市场仓库托管多个具有独立版本线的插件。--v 分隔符被解析为完整插件名称的前缀匹配，因此包含连字符的插件名称也能正确处理。

当你安装一个声明 { "name": "secrets-vault", "version": "~2.1.0" } 的插件时，Claude Code 会列出该市场的标签，过滤出以 secrets-vault--v 开头的标签，并获取满足 ~2.1.0 的最高版本。如果没有匹配的标签，依赖插件会被禁用，并显示可用版本列表。

已解析标签的 semver 与 plugin.json 的 version 分开记录，因此即使该提交的 plugin.json 中的版本过时，约束检查仍使用实际获取的标签。对于通过标签解析的安装，缓存目录名称包含一个 12 字符的提交 SHA 后缀，因此如果维护者将标签强制移动到不同提交，下次安装会获得一个新的缓存目录，而不是重用旧内容。

对于 npm 市场源，约束不控制获取哪个版本，因为基于标签的解析仅适用于 git 支持的市场源。约束在加载时仍会被检查，如果安装的版本不满足约束，依赖插件会因 dependency-version-unsatisfied 错误而被禁用。

约束如何交互

当多个已安装的插件约束同一个依赖时，Claude Code 会取它们的范围交集，并将依赖解析为满足所有范围中的最高版本。下表显示了常见组合的解析结果。

插件 A 要求	插件 B 要求	结果
^2.0	>=2.1	安装一个版本，取最高 2.x 标签且不低于 2.1.0。两个插件都能加载。
~2.1	~3.0	插件 B 安装失败，提示 range-conflict。插件 A 和依赖保持原样。
=2.1.0	无	依赖保持在 2.1.0。只要插件 A 已安装，自动更新会跳过更新的版本。

自动更新会获取满足所有已安装插件范围的最高的 git 标签，而不是市场的最新版本，因此依赖在其允许范围内会持续接收更新。如果没有标签满足所有范围，更新会被跳过，并在 /doctor 和 /plugin 的 Errors 标签页中显示，同时标明约束插件。

当你卸载最后一个约束某个依赖的插件时，该依赖不再被锁定，下次更新时将恢复追踪其市场条目。

启用或禁用带依赖的插件

启用一个插件也会启用它所依赖的插件，禁用某个插件时，如果另一个启用中的插件仍需要它，则禁用会被阻止。这两种行为都需要 Claude Code v2.1.143 或更高版本。更早的版本只启用或禁用指定的插件，并在下次加载时抛出 dependency-unsatisfied 错误。

当你启用一个插件时，Claude Code 会在相同作用域下同时启用它的依赖。如果依赖本身还有依赖，Claude Code 也会启用那些。成功消息会列出除你指定的插件外还启用了哪些插件。如果某个依赖无法启用，命令会拒绝执行，并告诉你是什么阻碍了以及如何修复：

条件	结果
某个依赖未安装	启用失败，并打印每个缺失依赖的 claude plugin install 命令。
某个依赖被组织插件策略阻止	启用失败，并列出被阻止的依赖名称。
某个依赖在优先级高于目标作用域的作用域上设置为 false	启用失败。在该作用域上启用该依赖，或使用 --scope 写到那里。
所有依赖都已安装且允许	启用成功，并为插件以及每个在目标作用域上尚未启用的依赖写入 true。

当你禁用某个插件时，如果其他已启用的插件仍依赖它，Claude Code 会拒绝。错误信息会列出依赖该插件的插件，并给出一个链式命令，按正确顺序禁用它们，最后是你请求禁用的那个。

例如，如果 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

从错误消息中复制链式命令，一步禁用整个集合。

清理自动安装的孤立依赖

自动安装的依赖在卸载依赖它们的插件后仍会保留在磁盘上，以防你重新安装依赖插件或希望直接继续使用该依赖。要清理它们，运行 claude plugin prune 列出不再有已安装插件需要的自动安装依赖，并在确认提示后移除它们。这需要 Claude Code v2.1.121 或更高版本。

claude plugin prune

默认情况下，prune 在用户作用域下操作。使用 --scope project 或 --scope local 以不同作用域为目标。传递 --dry-run 列出将要移除的内容而不实际更改。传递 -y 跳过确认提示。当 stdin 或 stdout 不是终端时，prune 会列出孤立依赖并退出，除非传递了 -y。

要在卸载时一并清理，给 claude plugin uninstall 传递 --prune。在移除指定插件后，Claude Code 会扫描并移除任何现在成为孤立的自动安装依赖。你自行安装的插件永远不会被清理，只有通过另一个插件的 dependencies 数组自动安装的才会被清理。

例如，要卸载 deploy-kit 并清理其留下的依赖：

claude plugin uninstall deploy-kit --prune

依赖错误排查

依赖问题会在 claude plugin list、/plugin 界面和 /doctor 中显示。受影响的插件会被禁用，直到你解决错误。下面列出最常见的错误及修复方法。

错误	含义	解决方法
dependency-unsatisfied	声明的依赖未安装，或已安装但被禁用。	运行错误消息中显示的 claude plugin install 命令。如果依赖的市场尚未配置，用 claude plugin marketplace add 添加它，Claude Code 会自动解析依赖。如果依赖被禁用，启用它。
range-conflict	某个依赖的版本要求无法合并。错误消息指出原因：没有版本满足所有范围、范围不是有效的 semver 语法、或合并后的范围过于复杂无法取交集。	卸载或更新其中一个冲突的插件，修复任何无效的 version 字符串，简化长的 `
dependency-version-unsatisfied	已安装依赖的版本不在该插件的声明范围内。	运行 claude plugin install <依赖名>@<市场名> 以所有当前约束重新解析依赖。
no-matching-tag	依赖的仓库没有满足范围的 {name}--v* 标签。	检查上游是否按约定发布了标签，或放宽你的范围。

要以编程方式检查这些错误，运行 claude plugin list --json 并读取每个插件的 errors 字段。

常见问题

跨市场依赖报错 cross-marketplace 怎么解决？

确保目标市场名称已添加到根市场的 marketplace.json 中的 allowCrossMarketplaceDependenciesOn 数组里。如果字段缺失或未包含目标市场，Claude Code 会拒绝自动安装。你可以先手动安装该依赖，这样无需修改许可列表也能满足约束。

依赖范围冲突 range-conflict 该如何处理？

冲突发生在一个依赖被多个插件要求了无法兼容的版本范围时。错误消息会说明具体原因。解决方法：卸载或更新其中一个冲突的插件，修复无效的 semver 字符串，简化长的 || 链，或请求上游作者放宽其约束。

为什么自动更新后依赖版本没有变化？

如果你的插件声明了版本约束（如 ~2.1.0），自动更新会选择满足所有已安装插件约束的最高 git 标签，而不是市场的最新版本。如果没有任何标签满足所有范围，更新会被跳过，并在 /doctor 和 /plugin 的 Errors 标签中显示。这是设计行为，避免因未测试的上游更新破坏你的工作。

参见

• 创建插件：使用技能、代理和钩子构建插件
• 创建和分发插件市场：为你的团队托管插件
• 插件参考：完整的 plugin.json 结构
• 版本管理：插件自身版本如何解析并用作缓存键