是什么
Plugin 可以在 plugin.json 中声明对其他 Plugin 的依赖,并通过 semver 版本约束锁定兼容范围。当上游 Plugin 发布破坏性变更时,版本约束防止自动更新破坏依赖方。需要 Claude Code v2.1.110+。
核心机制
依赖声明:在 plugin.json 的 dependencies 数组中声明:
{
"name": "deploy-kit",
"version": "3.1.0",
"dependencies": [
"audit-logger",
{ "name": "secrets-vault", "version": "~2.1.0" }
]
}版本约束语法:使用 Node.js semver 语法:
~2.1.0:允许 patch 更新(2.1.x)^2.0:允许 minor 更新(2.x.x)>=1.4:大于等于=2.1.0:精确版本
自动安装:安装含依赖的 Plugin 时,Claude Code 自动解析并安装依赖,在安装输出末尾列出新增的依赖。
跨 Marketplace 依赖:默认禁止,需要根 Marketplace 在 marketplace.json 中配置 allowCrossMarketplaceDependenciesOn:
{
"allowCrossMarketplaceDependenciesOn": ["acme-shared"]
}依赖恢复:依赖丢失时,/reload-plugins 或重新安装依赖方 Plugin 会自动恢复(前提是 Marketplace 已配置)。
关键细节
- 依赖字段:
name(必需)、version(semver 范围)、marketplace(跨 Marketplace 时指定) - Pre-release 版本默认排除,需用
^2.0.0-0等形式显式包含 - 依赖解析在同一 Marketplace 内进行,除非指定
marketplace字段 - 跨 Marketplace 信任不传递,只看根 Marketplace 的 allowlist
关联
- plugins — Plugin 创建指南
- plugin-marketplaces — Marketplace 配置,包括跨 Marketplace 依赖授权
实践要点
- 版本约束是 Plugin 作者的责任,用户侧无需关心
~2.1.0是最常用的约束,允许 bug fix 更新但防止 API 变更- 跨 Marketplace 依赖需要两个 Marketplace 维护者协调,谨慎使用
- 不设置
version的依赖跟踪最新版,适合内部工具但不适合公开分发