Claude Code官方文档插件依赖管理

Claude Code 插件依赖版本约束 - 兼容性管理与 breaking change

在插件依赖上声明版本约束，以便当上游插件发布破坏性变更时，你的插件继续正常工作。

· 阅读约 12 分钟

插件可以通过在 plugin.json 或其 marketplace 条目中列出其他插件来依赖它们。默认情况下，依赖会跟踪最新可用版本，因此上游发布可能会在没有警告的情况下更改你的插件下的依赖。版本约束让你可以将依赖保持在经过测试的版本范围内，直到你选择升级。

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

本指南适用于在 plugin.json 中声明依赖的插件作者和标记发布的 marketplace 维护者。要安装具有依赖的插件，请参阅 发现和安装插件。有关完整的 manifest 架构，请参阅 插件参考。

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

为什么要约束依赖版本

考虑一个内部 marketplace，其中两个团队发布插件。平台团队维护 secrets-vault，这是一个包装 secrets 后端的 MCP 服务器。部署团队维护 deploy-kit，它在部署期间调用 secrets-vault 来获取凭证。

deploy-kit 针对 secrets-vault v2.1.0 进行了测试。没有版本约束的情况下，下次平台团队标记一个重命名 MCP 工具的发布时，自动更新会将每个工程师的 secrets-vault 移动到新版本，deploy-kit 就会中断。

有了版本约束，deploy-kit 声明它需要 secrets-vault 在 ~2.1.0 范围内。安装了 deploy-kit 的工程师会停留在最高匹配的 2.1.x 补丁版本上。部署团队通过发布具有更宽松约束的新 deploy-kit 版本，按照自己的时间表进行升级。

声明具有版本约束的依赖

在插件的 .claude-plugin/plugin.json 的 dependencies 数组中列出依赖。每个条目要么是插件名称，要么是具有版本约束的对象。

以下 manifest 声明了一个无版本依赖和一个受约束的依赖：

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

条目可以是仅包含插件名称的裸字符串，如上例中的 "audit-logger"，它依赖于该插件的 marketplace 提供的任何版本。为了获得更多控制，请使用具有以下字段的对象：

字段类型描述
namestring插件名称。在与声明插件相同的 marketplace 中解析。必需。
versionstring一个 semver 范围，例如 ~2.1.0、^2.0、>=1.4 或 =2.1.0。依赖会在满足此范围的最高标记版本处获取。
marketplacestring一个不同的 marketplace 来在其中解析 name。跨 marketplace 依赖被阻止，除非目标 marketplace 在根 marketplace 的 marketplace.json 中的 allowCrossMarketplaceDependenciesOn 中列出。

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

依赖来自另一个 marketplace 的插件

默认情况下，Claude Code 拒绝自动安装位于与声明它的插件不同的 marketplace 中的依赖。这可以防止一个 marketplace 无声地从你未审查的来源拉入插件。

要允许这样做，根 marketplace 的维护者将目标 marketplace 名称添加到 marketplace.json 中的 allowCrossMarketplaceDependenciesOn。根 marketplace 是托管用户正在安装的插件的那个；只有其允许列表被查询，因此信任不会通过中间 marketplace 链接。

以下 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" }
      ]
    }
  ]
}

如果字段缺失或不包含目标 marketplace，安装会失败并显示 cross-marketplace 错误，命名要设置的字段。用户仍然可以手动先安装依赖，这会满足约束而无需更改允许列表。

标记插件发布以进行版本解析

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

将每个发布标记为 {plugin-name}--v{version}，其中 {version} 与该提交的 plugin.json 中的 version 字段匹配。从插件目录中，运行：

claude plugin tag --push

claude plugin tag 命令从插件的清单和封闭的 marketplace 条目派生标签名称。在创建标签之前，它验证插件内容，检查 plugin.json 和 marketplace 条目是否在版本上一致，要求插件目录下的工作树干净，如果标签已存在则拒绝。添加 --dry-run 以查看将被标记的内容而不创建它。

插件名称前缀让一个 marketplace 存储库可以托管多个具有独立版本线的插件。--v 分隔符被解析为完整插件名称上的前缀匹配，因此包含连字符的插件名称会被正确处理。

当你安装声明了 { "name": "secrets-vault", "version": "~2.1.0" } 的插件时，Claude Code 会列出 marketplace 的标签，过滤到以 secrets-vault--v 开头的标签，并获取满足 ~2.1.0 的最高版本。如果不存在匹配的标签，依赖插件会被禁用并显示错误，列出可用的版本。

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

ℹ️ 对于 npm marketplace 源，约束不控制获取哪个版本，因为基于标签的解析仅适用于 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 标签处获取受约束的依赖，而不是在 marketplace 的最新版本处，因此依赖继续在其允许的范围内接收更新。如果没有标签满足所有范围，更新会被跳过，跳过消息会出现在 /doctor 和 /plugin 错误选项卡中，并命名约束插件。

当你卸载最后一个约束依赖的插件时，该依赖不再被保持，并在下次更新时恢复跟踪其 marketplace 条目。

删除孤立的自动安装依赖

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

claude plugin prune

默认情况下，prune 在用户范围内运行。使用 --scope project 或 --scope local 来针对不同的范围。传递 --dry-run 来列出将被删除的内容而不进行任何更改。传递 -y 来跳过确认提示。当 stdin 或 stdout 不是终端时，prune 会列出孤立项并退出，除非传递了 -y。

要在卸载过程中进行 prune，请将 --prune 传递给 claude plugin uninstall。删除命名的插件后，Claude Code 会扫描并删除现在孤立的任何自动安装依赖。你自己安装的插件永远不会被 prune，只有通过另一个插件的 dependencies 数组自动安装的插件才会被 prune。

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

claude plugin uninstall deploy-kit --prune

解决依赖错误

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

错误含义如何解决
dependency-unsatisfied声明的依赖未安装，或已安装但被禁用运行错误消息中显示的 claude plugin install 命令。如果依赖的 marketplace 尚未配置，使用 claude plugin marketplace add 添加它，Claude Code 会自动解析依赖。如果依赖被禁用，请启用它
range-conflict依赖的版本要求无法组合。错误消息命名原因：没有版本满足所有范围，范围不是有效的 semver 语法，或组合范围太复杂而无法交集卸载或更新其中一个冲突的插件，修复任何无效的 version 字符串，简化长 || 链，或要求上游作者扩大其约束
dependency-version-unsatisfied已安装的依赖版本在此插件的声明范围之外运行 claude plugin install <dependency>@<marketplace> 以根据所有当前约束重新解析依赖
no-matching-tag依赖的存储库没有满足范围的 {name}--v* 标签检查上游是否使用上述约定标记了发布，或放宽你的范围

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

另请参阅

本文翻译自 Anthropic Claude Code 官方文档，最近一次同步：2025-05-01。