是什么

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

关联

实践要点

  • 版本约束是 Plugin 作者的责任,用户侧无需关心
  • ~2.1.0 是最常用的约束,允许 bug fix 更新但防止 API 变更
  • 跨 Marketplace 依赖需要两个 Marketplace 维护者协调,谨慎使用
  • 不设置 version 的依赖跟踪最新版,适合内部工具但不适合公开分发