约束插件依赖版本¶

在 plugin.json 中声明版本约束，让你的插件在上游发布破坏性变更时仍能正常工作。

插件可以通过 plugin.json 或市场条目中列出依赖。默认情况下依赖跟踪最新版本，上游发布可能在不通知的情况下改变依赖。版本约束让你将依赖锁定在经测试的版本范围内。

安装声明了依赖的插件时，Claude Code 自动解析并安装依赖，并在安装输出末尾列出添加的依赖。如果依赖后来丢失，/reload-plugins 和后台自动更新会重新安装（前提是其市场已在你配置的市场中）。重新运行 claude plugin install 或用 claude plugin marketplace add 添加市场也会解析未满足的依赖。来自未添加市场的依赖不会被解析。

本指南面向在 plugin.json 中声明依赖的插件作者和标记发布的市场维护者。安装带依赖的插件见 Discover and install plugins。完整清单 schema 见 Plugins reference。

为什么要约束依赖版本¶

场景示例： 平台团队维护 secrets-vault v2.1.0，部署团队的 deploy-kit 调用它获取凭据。没有版本约束，平台团队重命名 MCP 工具后，自动更新会移动所有人的 secrets-vault 到新版本，deploy-kit 就坏了。

有了 ~2.1.0 约束，用户保持在最高匹配的 2.1.x 补丁版本。部署团队按自己的节奏升级——发布新版 deploy-kit 并扩大约束范围。

声明带版本约束的依赖¶

在 plugin.json 的 dependencies 数组中列出。每个条目可以是插件名字符串或带版本约束的对象：

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

裸字符串（如 "audit-logger"）依赖该插件市场提供的任意版本。对象形式字段：

version 字段接受 Node semver 包支持的任何表达式，包括 caret、tilde、hyphen 和 comparator 范围。预发布版本（如 2.0.0-beta.1）默认排除，除非范围用预发布后缀明确纳入（如 ^2.0.0-0）。

为团队打包插件集¶

插件清单可以仅由 name 和 dependencies 数组组成，安装它会拉入所有依赖——这是打包一组精选插件的方式。

例如，平台团队可以在内部市场发布角色专用 bundle，工程师运行一次 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 会解析并安装所有四个依赖。

后续要为标准集添加工具，发布带新依赖的 backend-standard 新版本。非 Anthropic 市场默认关闭自动更新，工程师有两种方式接收新版：

• 在 /plugin 中为该市场启用自动更新。下次自动更新会将 bundle 移到新版并安装新增依赖。
• 运行 claude plugin update backend-standard，然后 /reload-plugins 安装新依赖。

要在组织范围推出 bundle，将 bundle 插件添加到 managed settings 的 enabledPlugins。

跨市场依赖¶

默认 Claude Code 拒绝自动安装来自不同市场的依赖。 这防止一个市场静默拉入你未审查来源的插件。

要允许，根市场维护者在 marketplace.json 中添加目标市场名到 allowCrossMarketplaceDependenciesOn。根市场是托管用户正在安装的插件的市场；仅查询它的白名单，信任不会通过中间市场传递。

{
  "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 tag 解析。 上游插件必须用特定命名约定标记发布。

标记格式：{plugin-name}--v{version}，其中 {version} 匹配该 commit 的 plugin.json 中的 version 字段。从插件目录运行：

claude plugin tag --push

该命令从插件清单和市场条目推导 tag 名。创建 tag 前它会：验证插件内容、检查 plugin.json 和市场条目版本一致、要求插件目录下工作树干净、tag 已存在则拒绝。

• --push 将 tag 推送到 origin 远程。用 --remote 推送到其他远程。
• 推送失败时 tag 仍在本地创建，命令以错误退出。
• 使用 --push 时，成功输出以 Created tag secrets-vault--v2.1.0 和 Pushed to origin 结束。不用 --push 时打印要运行的 git push 命令。
• --dry-run 预览将创建什么 tag 而不实际创建。

直接运行 git tag secrets-vault--v2.1.0 等效（前提是你自行保持 plugin.json 和市场条目同步）。

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

安装 { "name": "secrets-vault", "version": "~2.1.0" } 时，Claude Code 列出市场 tag，过滤 secrets-vault--v 开头的，取满足 ~2.1.0 的最高版本。无匹配 tag 则禁用依赖插件并列出可用版本。

以本地文件夹路径添加的市场，当文件夹是 git 仓库时同样解析 tag（需 v2.1.196+）。两种情况下 Claude Code 直接从文件夹当前内容安装：

• 更早版本不从本地文件夹市场读取 tag
• 非 git 仓库的本地文件夹无 tag

解析的 tag semver 与 plugin.json 的 version 分开记录，约束检查使用实际获取的 tag。tag 解析安装的缓存目录名包含 12 字符 commit-SHA 后缀，维护者 force-move tag 后下次安装获得新缓存目录。

[!NOTE]
对于 npm 市场源，约束不控制获取的版本（tag 解析仅适用于 git 源）。约束仍在加载时检查，不满足时依赖插件以 dependency-version-unsatisfied 禁用。

约束交互¶

多个已安装插件约束同一依赖时，Claude Code 取交集并解析满足所有约束的最高版本。

自动更新在所有已安装插件范围内取满足的最高 git tag（而非市场最新版），依赖继续在允许范围内接收更新。如果无 tag 满足所有范围，自动更新跳过该依赖并在 /plugin Errors 标签列出跳过原因和约束插件。

卸载最后一个约束依赖的插件后，依赖恢复跟踪市场条目。

启用/禁用带依赖的插件¶

启用插件也启用其依赖；禁用被其他启用的插件依赖的插件会被阻止。 需要 v2.1.143+。更早版本仅启用/禁用指定插件，下次加载时报 dependency-unsatisfied 错误。

启用插件时，Claude Code 在同一作用域启用其依赖（递归）。成功消息列出同时启用的内容。依赖无法启用时，命令拒绝并说明原因：

即使依赖设置了 defaultEnabled: false，Claude Code 也会为其写入显式 true。安装时同理：被活跃插件需要的依赖安装为 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 列出不再被任何已安装插件需要的自动安装依赖，确认后移除。需 v2.1.121+。

claude plugin prune

如果没有可清理的内容，命令打印 Nothing to prune 并给出原因。这是全新安装的预期输出，不是错误。

默认 prune 操作用户作用域，移除前询问确认：

• --scope project 或 --scope local 指定其他作用域
• --dry-run 预览而不修改
• -y 跳过确认提示。stdin/stdout 不是终端时，prune 列出孤立项但不移除，除非传 -y

卸载时顺带清理，传 --prune 给 claude plugin uninstall。移除指定插件后，Claude Code 扫描并移除现在孤立的自动安装依赖。你自己安装的插件永远不会被 prune——仅通过另一插件 dependencies 数组自动安装的才会。

确认行为相同：传 -y 跳过提示。stdin/stdout 不是终端时，卸载仍完成，但 prune 步骤列出孤立项但不移除，除非传 -y。

示例——卸载 deploy-kit 并清理其遗留依赖：

claude plugin uninstall deploy-kit --prune

解决依赖错误¶

依赖问题出现在 claude plugin list 和 /plugin 界面中，作为描述性错误消息（非下表中的字面代码）。Claude Code 禁用受影响的插件直到你解决错误。

编程检查：claude plugin list --json。有问题的插件包含 errors 字段；正常加载的插件省略该字段。

另见¶

• Create plugins — 构建含技能、agent 和 hooks 的插件
• Plugin marketplaces — 为团队托管插件
• Plugins reference — 完整 plugin.json schema
• Version management — 插件自身版本的解析方式