plugin-dependencies.md +0 −267 deleted
File Deleted View Diff
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# 约束插件依赖版本
6
7> 在插件依赖上声明版本约束，并将精选插件集合捆绑在一个安装后面。
8
9插件可以通过在 `plugin.json` 或其 marketplace 条目中列出其他插件来依赖它们。默认情况下，依赖会跟踪最新可用版本，因此上游发布可能会在没有警告的情况下更改你的插件下的依赖。版本约束让你可以将依赖保持在经过测试的版本范围内，直到你选择升级。
10
11当你安装声明了依赖的插件时，Claude Code 会自动解析并安装它们，除了其 marketplace 条目具有 [`command` 源](/docs/zh-CN/plugin-marketplaces#how-users-accept-the-command) 或 [`headersHelper`](/docs/zh-CN/plugin-marketplaces#how-users-accept-a-headershelper-command) 的依赖，你需要先自己安装。之后，`/reload-plugins`、依赖插件 marketplace 的自动更新、在依赖插件上重新运行 `claude plugin install`，以及 `claude plugin marketplace add` 都会在相同规则下安装任何尚未安装的声明依赖；如果某个依赖保持未解决状态，请参阅[解决依赖错误](#resolve-dependency-errors)。
12
13本指南适用于在 `plugin.json` 中声明依赖的插件作者和标记发布的 marketplace 维护者。这里的依赖是其他插件；对于插件本身使用的 npm 和 Bun 包，请参阅 [Node.js 包依赖](/docs/zh-CN/plugins-reference#node-js-package-dependencies)。要安装具有依赖的插件，请参阅[发现和安装插件](/docs/zh-CN/discover-plugins)。有关完整的 manifest 架构，请参阅[插件参考](/docs/zh-CN/plugins-reference)。
14
15<h2 id="why-constrain-dependency-versions">
16 为什么要约束依赖版本
17</h2>
18
19考虑一个内部 marketplace，其中两个团队发布插件。平台团队维护 `secrets-vault`，这是一个包装 secrets 后端的 MCP 服务器。部署团队维护 `deploy-kit`，它在部署期间调用 `secrets-vault` 来获取凭证。
20
21`deploy-kit` 针对 `secrets-vault` v2.1.0 进行了测试。没有版本约束的情况下，下次平台团队标记一个重命名 MCP 工具的发布时，自动更新会将每个工程师的 `secrets-vault` 移动到新版本，`deploy-kit` 就会中断。
22
23有了版本约束，`deploy-kit` 声明它需要 `secrets-vault` 在 `~2.1.0` 范围内。安装了 `deploy-kit` 的工程师会停留在最高匹配的 `2.1.x` 补丁版本上。部署团队通过发布具有更宽松约束的新 `deploy-kit` 版本，按照自己的时间表进行升级。
24
25<h2 id="declare-a-dependency-with-a-version-constraint">
26 声明具有版本约束的依赖
27</h2>
28
29在插件的 `.claude-plugin/plugin.json` 的 `dependencies` 数组中列出依赖。
30
31以下 manifest 声明了一个无版本依赖和一个受约束的依赖：
32
33```json .claude-plugin/plugin.json theme={null}
34{
35 "name": "deploy-kit",
36 "version": "3.1.0",
37 "dependencies": [
38 "audit-logger",
39 { "name": "secrets-vault", "version": "~2.1.0" }
40 ]
41}
42```
43
44条目可以是仅包含插件名称的裸字符串，如 `"audit-logger"` 在 `deploy-kit` manifest 中，它依赖于该插件的 marketplace 提供的任何版本。为了获得更多控制，请使用具有以下字段的对象：
45
46| 字段 | 类型 | 描述 |
47| :------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
48| `name` | string | 插件名称。在与声明插件相同的 marketplace 中解析。必需。 |
49| `version` | string | 一个 [semver 范围](https://github.com/npm/node-semver#ranges)，例如 `~2.1.0`、`^2.0`、`>=1.4` 或 `=2.1.0`。依赖会在满足此范围的最高标记版本处获取。 |
50| `marketplace` | string | 一个不同的 marketplace 来在其中解析 `name`。跨 marketplace 依赖被阻止，除非目标 marketplace 在根 marketplace 的 `marketplace.json` 中的 [`allowCrossMarketplaceDependenciesOn`](#depend-on-a-plugin-from-another-marketplace) 中列出。 |
51
52预发布版本（如 `2.0.0-beta.1`）被排除，除非你的范围使用预发布后缀（如 `^2.0.0-0`）选择加入。
53
54<h2 id="bundle-plugins-for-a-team">
55 为团队捆绑 plugins
56</h2>
57
58除了必需的 `name` 之外，plugin manifest 可以仅包含一个 `dependencies` 数组。安装它会拉取每个依赖项，这使其成为在一个安装后面打包精选 plugin 集的一种方式。
59
60例如，平台团队可以在内部 marketplace 中发布特定角色的捆绑包，这样工程师只需运行一次 `claude plugin install`，而不是分别安装每个工具：
61
62```json .claude-plugin/plugin.json theme={null}
63{
64 "name": "backend-standard",
65 "version": "1.0.0",
66 "description": "Standard plugin set for backend engineers",
67 "dependencies": [
68 "secrets-vault",
69 "deploy-kit",
70 { "name": "db-migrate", "version": "^3.0" },
71 "oncall-runbook"
72 ]
73}
74```
75
76安装 `backend-standard` 会解析并安装所有四个依赖项。
77
78要稍后向标准集添加工具，请发布新的 `backend-standard` 版本并添加额外的依赖项。除非 marketplace [自动更新](/docs/zh-CN/discover-plugins#configure-auto-updates)，工程师可以通过以下两种方式之一获取新版本：
79
80* 在 `/plugin` 中为 marketplace 启用自动更新。下一次自动更新会将捆绑包移至新版本并安装它添加的任何依赖项。
81* 运行 `claude plugin update backend-standard`，然后运行 `/reload-plugins` 以安装新添加的依赖项。
82
83要在整个组织中推出捆绑包，请将捆绑 plugin 添加到[托管设置](/docs/zh-CN/settings-reference#enabledplugins)中的 `enabledPlugins`。
84
85<h2 id="depend-on-a-plugin-from-another-marketplace">
86 依赖来自另一个 marketplace 的插件
87</h2>
88
89默认情况下，Claude Code 拒绝自动安装位于与声明它的插件不同的 marketplace 中的依赖。这可以防止一个 marketplace 无声地从你未审查的来源拉入插件。
90
91要允许这样做，根 marketplace 的维护者将目标 marketplace 名称添加到 `marketplace.json` 中的 `allowCrossMarketplaceDependenciesOn`。根 marketplace 是托管用户正在安装的插件的那个；只有其允许列表被查询，因此信任不会通过中间 marketplace 链接。
92
93以下 `marketplace.json` 允许 `deploy-kit` 依赖来自 `acme-shared` 的插件：
94
95```json .claude-plugin/marketplace.json theme={null}
96{
97 "name": "acme-tools",
98 "owner": { "name": "Acme" },
99 "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
100 "plugins": [
101 {
102 "name": "deploy-kit",
103 "source": "./deploy-kit",
104 "dependencies": [
105 { "name": "audit-logger", "marketplace": "acme-shared" }
106 ]
107 }
108 ]
109}
110```
111
112如果字段缺失或不包含目标 marketplace，安装会失败并显示 `cross-marketplace` 错误，命名要设置的字段。用户仍然可以手动先安装依赖，这会满足约束而无需更改允许列表。
113
114<h2 id="test-a-plugin-and-its-dependency-locally">
115 在本地测试插件及其依赖项
116</h2>
117
118如果你同时开发一个插件和它所依赖的插件，请使用 `--plugin-dir` 加载两者：
119
120```bash theme={null}
121claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin
122```
123
124依赖项的本地副本满足你的插件的依赖项条目，即使该条目命名了一个marketplace，所以你不需要从其marketplace安装依赖项。Claude Code不会对本地副本检查[版本约束](#declare-a-dependency-with-a-version-constraint)，所以本地 `plugin.json` 不需要 `version`。在v2.1.242之前，命名marketplace的依赖项条目从不匹配本地副本，Claude Code会在加载时禁用你的插件。
125
126当两个插件位于同一个父文件夹中时，你可以将该文件夹传递给 `--plugin-dir` 一次。如果该文件夹本身不是插件，Claude Code会加载每个具有 `.claude-plugin/plugin.json` 的子文件夹。需要Claude Code v2.1.265或更高版本。
127
128如果你还没有从其marketplace安装依赖项，当本地副本消失时，你的插件会停止加载：
129
130* **你禁用了本地副本**：Claude Code会在下一次插件加载时禁用你的插件。对于命名marketplace的依赖项条目，Claude Code会报告 `Dependency "<name>@inline" is disabled — enable it or remove the dependency`；对于裸名条目，它会按其裸名报告依赖项。`<name>@inline` 是Claude Code识别每个 `--plugin-dir` 和 `--plugin-url` 插件的方式。
131* **你启动了一个没有依赖项的 `--plugin-dir` 标志的会话**：Claude Code会报告依赖项未安装。再次传递该标志，或从其marketplace安装依赖项。
132
133<h2 id="tag-plugin-releases-for-version-resolution">
134 用于版本解析的标签插件发布
135</h2>
136
137Claude Code 针对托管依赖项的存储库上的 git 标签解析版本约束：对于 `github`、`url` 和 `git-subdir` [插件源](/docs/zh-CN/plugin-marketplaces#plugin-sources)，使用插件自己的存储库；对于市场通过相对路径引用的插件，使用市场存储库。为了让 Claude Code 找到依赖项的可用版本，上游插件的发布必须使用特定的命名约定进行标记。
138
139将每个发布标记为 `{plugin-name}--v{version}`，其中 `{version}` 与该提交的 `plugin.json` 中的 `version` 字段匹配。从插件目录运行：
140
141```bash theme={null}
142claude plugin tag --push
143```
144
145`claude plugin tag` 命令从插件的清单和封闭的市场条目派生标签名称。在创建标签之前，它验证插件内容，检查 `plugin.json` 和市场条目是否在版本上一致，要求插件目录下的工作树干净，如果标签已存在则拒绝。
146
147* `--push` 将标签推送到 `origin` 远程，因此存储库需要配置 `origin` 远程。传递 `--remote` 以推送到不同的远程。
148* 如果推送失败，标签仍会在本地创建，命令以错误退出。
149* 使用 `--push`，成功运行以 `Created tag secrets-vault--v2.1.0` 和 `Pushed to origin` 结束，其中最后一行命名推送到的远程。不使用 `--push`，命令改为打印要运行的 `git push` 命令。
150* `--dry-run` 打印将被标记的内容而不创建它。
151
152直接运行 `git tag secrets-vault--v2.1.0` 是等效的，如果你自己保持 `plugin.json` 和市场条目同步。
153
154插件名称前缀允许一个市场存储库托管多个具有独立版本线的插件。`--v` 分隔符被解析为完整插件名称的前缀匹配，因此包含连字符的插件名称被正确处理。
155
156当你安装声明 `{ "name": "secrets-vault", "version": "~2.1.0" }` 的插件时，Claude Code 列出托管 `secrets-vault` 的存储库上的标签，筛选以 `secrets-vault--v` 开头的标签，并获取满足 `~2.1.0` 的最高版本。如果插件自己的存储库上没有标签满足该范围，安装失败并显示 `Dependency "secrets-vault@acme-tools" has no git tag satisfying ~2.1.0`，这命名了依赖项及其市场。对于没有匹配标签的相对路径插件，Claude Code 改为安装市场的当前副本，并在插件加载时检查约束。
157
158对于市场通过相对路径引用的插件，添加为本地文件夹路径的市场在文件夹是 git 存储库时以相同方式解析标签。这需要 Claude Code v2.1.196 或更高版本。在两种情况下，Claude Code 改为从文件夹的当前内容安装依赖项：
159
160* 早期版本不从本地文件夹市场读取标签，因此受约束的依赖项仅在该副本满足范围时加载。
161* 不是 git 存储库的本地文件夹没有标签，无论版本如何。
162
163已解析标签的 semver 与 `plugin.json` 的 `version` 分开记录，因此约束检查使用实际获取的标签，即使该提交处的 `plugin.json` 有陈旧值。标签解析安装的缓存目录名称包括 12 字符的提交 SHA 后缀，因此如果维护者强制将标签移动到不同的提交，下次安装会获得新的缓存目录，而不是重用陈旧内容。
164
165<Note>
166 对于具有 `npm`、`archive` 或 `command` [插件源](/docs/zh-CN/plugin-marketplaces#plugin-sources) 的依赖项，约束不控制获取哪个版本，因为基于标签的解析仅适用于 git 支持的源。约束仍在加载时检查，如果安装的版本不满足它，依赖插件将被禁用并显示 `dependency-version-unsatisfied`。对于 `command` 源，Claude Code 检查依赖项的 `plugin.json` 中的版本并忽略内容哈希后缀；其 `plugin.json` 未设置版本的依赖项不满足任何约束，因此在约束它之前设置一个。
167
168 Claude Code 从不自己安装具有 `command` 源的依赖项，因此用户 [首先安装它](/docs/zh-CN/plugin-marketplaces#how-users-accept-the-command)。Claude Code 也从不在依赖项的市场条目上运行 `headersHelper`，因此用户 [首先安装该插件](/docs/zh-CN/plugin-marketplaces#how-users-accept-a-headershelper-command)。
169</Note>
170
171<h2 id="how-constraints-interact">
172 约束如何相互作用
173</h2>
174
175当多个已安装的插件约束同一依赖时，Claude Code 会交集它们的范围，并将依赖解析为满足所有范围的最高版本。下表显示了常见组合如何解析。
176
177| 插件 A 需要 | 插件 B 需要 | 结果 |
178| :------- | :------ | :---------------------------------------------- |
179| `^2.0` | `>=2.1` | 在最高 `2.x` 标签处进行一次安装，该标签在 `2.1.0` 或更高版本。两个插件都加载。 |
180| `~2.1` | `~3.0` | 插件 B 的安装失败，显示 `range-conflict`。插件 A 和依赖保持原样。 |
181| `=2.1.0` | 无 | 依赖保持在 `2.1.0`。在安装了插件 A 时，自动更新会跳过较新版本。 |
182
183自动更新在满足每个已安装插件范围的最高 git 标签处获取受约束的依赖，而不是在 marketplace 的最新版本处，因此依赖继续在其允许的范围内接收更新。如果没有标签满足所有范围，自动更新会跳过该依赖，并在 `/plugin` 错误选项卡中列出跳过情况，命名约束插件。
184
185当你卸载最后一个约束依赖的插件时，该依赖不再被保持，并在下次更新时恢复跟踪其 marketplace 条目。
186
187<h2 id="enable-or-disable-a-plugin-with-dependencies">
188 启用或禁用具有依赖的插件
189</h2>
190
191本部分涵盖从市场安装的插件。对于使用 `--plugin-dir` 加载的副本，请参阅[在本地测试插件及其依赖](#test-a-plugin-and-its-dependency-locally)。
192
193启用插件也会启用它依赖的插件，禁用插件会被阻止，如果另一个已启用的插件仍然需要它。
194
195当你启用插件时，Claude Code 也会在同一范围内启用其依赖。如果依赖有自己的依赖，Claude Code 也会启用那些。成功消息会列出与你命名的插件一起启用的其他内容。如果依赖无法启用，命令会拒绝并告诉你什么在阻止以及如何修复：
196
197| 条件 | 结果 |
198| :-------------------------- | :------------------------------------------ |
199| 依赖未安装 | 启用失败并为每个缺失的依赖打印 `claude plugin install` 命令。 |
200| 依赖被你的组织的插件策略阻止 | 启用失败并命名被阻止的依赖。 |
201| 依赖在优先级高于目标范围的范围内设置为 `false` | 启用失败。在该范围内启用依赖，或传递 `--scope` 来在那里写入。 |
202| 所有依赖都已安装且被允许 | 启用成功并为插件和每个在目标范围内尚未启用的依赖写入 `true`。 |
203
204即使依赖在其清单中设置了 [`defaultEnabled: false`](/docs/zh-CN/plugins-reference#default-enablement)，这也成立，因为 Claude Code 为其写入显式 `true`。同样适用于安装：为满足活跃插件而引入的依赖会以 `true` 安装，无论其自身默认值如何。
205
206当你禁用插件时，Claude Code 会拒绝，如果另一个已启用的插件仍然依赖它。错误会命名依赖它的插件，并给你一个链式命令，以正确的顺序禁用它们，以你要求的那个结尾。
207
208例如，如果 `deploy-kit` 依赖 `secrets-vault`，单独禁用 `secrets-vault` 会失败，输出类似于以下内容：
209
210```text theme={null}
211secrets-vault is still required by deploy-kit. Disable that plugin first, or
212disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools
213```
214
215从错误中复制链式命令以一步禁用完整集合。
216
217<h2 id="remove-orphaned-auto-installed-dependencies">
218 删除孤立的自动安装依赖
219</h2>
220
221自动安装的依赖在安装它们的插件被卸载后仍会保留在磁盘上，以防你重新安装依赖插件或想继续直接使用该依赖。要清理它们，运行 `claude plugin prune` 来列出不再有任何已安装插件需要的自动安装依赖，并在确认提示后删除它们。
222
223```bash theme={null}
224claude plugin prune
225```
226
227如果没有任何内容符合删除条件，该命令会打印 `Nothing to prune` 并显示原因后退出。这是全新安装时的预期输出，不是错误。
228
229默认情况下，prune 在用户范围内运行，并在删除任何内容前要求确认：
230
231* `--scope project` 或 `--scope local` 针对不同的范围。
232* `--dry-run` 列出将被删除的内容而不进行任何更改。
233* `-y` 跳过确认提示。当 stdin 或 stdout 不是终端时，prune 会列出孤立项并退出，除非你传递 `-y`。
234
235要在卸载过程中进行 prune，请将 `--prune` 传递给 `claude plugin uninstall`。删除命名的插件后，Claude Code 会扫描并删除现在孤立的任何自动安装依赖。你自己安装的插件永远不会被 prune，只有通过另一个插件的 `dependencies` 数组自动安装的插件才会被 prune。
236
237相同的确认行为适用。当 stdin 或 stdout 不是终端时，卸载仍会完成，但 prune 步骤会列出孤立项，除非你传递 `-y`，否则不会删除任何内容。
238
239例如，要卸载 `deploy-kit` 并清理它留下的依赖：
240
241```bash theme={null}
242claude plugin uninstall deploy-kit --prune
243```
244
245<h2 id="resolve-dependency-errors">
246 解决依赖错误
247</h2>
248
249依赖问题会在 `claude plugin list` 和 `/plugin` 界面中显示为描述性错误消息，而不是此表中的字面代码。Claude Code 会禁用受影响的插件，直到你解决错误。下表列出了最常见的错误及其解决方法。
250
251| 错误 | 含义 | 如何解决 |
252| :------------------------------- | :--------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
253| `dependency-unsatisfied` | 声明的依赖未安装，或已安装但被禁用。 | 运行错误消息中显示的 `claude plugin install` 命令。如果依赖的 marketplace 尚未配置，使用 `claude plugin marketplace add` 添加它，Claude Code 会自动解析依赖。如果依赖被禁用，请启用它。 |
254| `range-conflict` | 依赖的版本要求无法组合。错误消息命名原因：没有版本满足所有范围，范围不是有效的 semver 语法，或组合范围太复杂而无法交集。 | 卸载或更新其中一个冲突的插件，修复任何无效的 `version` 字符串，简化长 `\|\|` 链，或要求上游作者扩大其约束。 |
255| `dependency-version-unsatisfied` | 已安装的依赖版本在此插件的声明范围之外。 | 运行 `claude plugin install <dependency>@<marketplace>` 以根据所有当前约束重新解析依赖。 |
256| `no-matching-tag` | 依赖的存储库没有满足范围的 `{name}--v*` 标签。 | 检查上游是否使用上述约定标记了发布，或放宽你的范围。 |
257
258要以编程方式检查这些错误，请运行 `claude plugin list --json`。有问题的插件包含一个 `errors` 字段列出这些错误。加载正常的插件会省略该字段。
259
260<h2 id="see-also">
261 另请参阅
262</h2>
263
264* [创建插件](/docs/zh-CN/plugins)：使用 skills、agents 和 hooks 构建插件
265* [创建和分发插件 marketplace](/docs/zh-CN/plugin-marketplaces)：为你的团队托管插件
266* [插件参考](/docs/zh-CN/plugins-reference#plugin-manifest-schema)：完整的 `plugin.json` 架构
267* [版本管理](/docs/zh-CN/plugins-reference#version-management)：插件自身版本如何被解析并用作缓存键