{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在此获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。

# 约束插件依赖版本

> 声明插件依赖的版本约束，以便在上游插件发布破坏性更改时您的插件仍能正常工作。

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

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

本指南适用于在 `plugin.json` 中声明依赖项的插件作者以及为发布打标签的市场维护者。要安装具有依赖项的插件，请参阅[发现和安装插件](/en/discover-plugins)。完整的清单架构请参阅[插件参考](/en/plugins-reference)。

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

## 为什么要约束依赖版本

考虑一个内部市场中有两个团队发布插件的场景。平台团队维护 `secrets-vault`，一个封装密钥后端的 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` 数组中列出依赖项。每个条目可以是插件名称或带有版本约束的对象。

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

```json .claude-plugin/plugin.json theme={null}
{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}
```

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

| 字段         | 类型   | 描述                                                                                                                                                                                                                                                             |
| :------------ | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string | 插件名称。在声明插件的同一市场中解析。必需。                                                                                                                                                                                    |
| `version`     | string | [semver 范围](https://github.com/npm/node-semver#ranges)，如 `~2.1.0`、`^2.0`、`>=1.4` 或 `=2.1.0`。依赖项将获取满足此范围的最高标签版本。                                                                          |
| `marketplace` | string | 用于解析 `name` 的不同市场。除非目标市场列在根市场的 `marketplace.json` 中的 [`allowCrossMarketplaceDependenciesOn`](#depend-on-a-plugin-from-another-marketplace) 中，否则跨市场依赖项将被阻止。 |

`version` 字段接受 Node 的 `semver` 包支持的任何表达式，包括脱字号、波浪号、连字符和比较器范围。预发布版本（如 `2.0.0-beta.1`）被排除在外，除非您的范围使用预发布后缀（如 `^2.0.0-0`）选择加入。

## 依赖另一个市场的插件

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

要允许这样做，根市场的维护者将目标市场名称添加到 `marketplace.json` 中的 `allowCrossMarketplaceDependenciesOn`。根市场是托管用户正在安装的插件的市场；仅检查其允许列表，因此信任不会通过中间市场链式传递。

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

```json .claude-plugin/marketplace.json theme={null}
{
  "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 找到依赖项的可用版本，上游插件的发布必须使用特定的命名约定进行标记。

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

```bash theme={null}
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 后缀，因此如果维护者将标签强制移动到不同的提交，下一次安装会获得新的缓存目录，而不是重用过时的内容。

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

## 约束如何交互

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

| 插件 A 要求 | 插件 B 要求 | 结果                                                                                          |
| :---------------- | :---------------- | :---------------------------------------------------------------------------------------------- |
| `^2.0`            | `>=2.1`           | 在 `2.1.0` 或以上的最高 `2.x` 标签处安装一次。两个插件都加载。                    |
| `~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` 会失败并显示类似以下的输出：

```text theme={null}
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 或更高版本。

```bash theme={null}
claude plugin prune
```

默认情况下，prune 在用户作用域下操作。使用 `--scope project` 或 `--scope local` 来定位不同的作用域。传递 `--dry-run` 可列出将被移除的内容而不进行更改。传递 `-y` 可跳过确认提示。当 stdin 或 stdout 不是终端时，prune 列出孤立项并退出，除非传递了 `-y`。

要在卸载时进行 prune，请将 `--prune` 传递给 `claude plugin uninstall`。在移除命名的插件后，Claude Code 扫描并移除任何现在孤立的自动安装依赖项。您自己安装的插件永远不会被 prune，只有通过其他插件的 `dependencies` 数组自动安装的才会。

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

```bash theme={null}
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 <dependency>@<marketplace>` 针对所有当前约束重新解析依赖项。                                                                                                                                                    |
| `no-matching-tag`                | 依赖项的仓库没有满足范围的 `{name}--v*` 标签。                                                                                                                                                         | 检查上游是否使用上述约定标记了发布，或放宽您的范围。                                                                                                                                                                            |

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

## 另请参阅

* [创建插件](/en/plugins)：使用技能、代理和钩子构建插件
* [创建和分发插件市场](/en/plugin-marketplaces)：为您的团队托管插件
* [插件参考](/en/plugins-reference#plugin-manifest-schema)：完整的 `plugin.json` 架构
* [版本管理](/en/plugins-reference#version-management)：插件自身的版本如何被解析并用作缓存键