约束插件依赖版本

为插件依赖声明版本范围，避免上游破坏性更新静默拖垮你的插件。

是什么

插件可以在 plugin.json 或 marketplace 条目中通过 dependencies 数组依赖其他插件。默认情况下依赖会跟踪最新可用版本，上游一发新版就可能在你毫不知情时改动依赖。版本约束（version constraint）让你把依赖锁定在已测试过的版本范围内，直到你主动升级。

该功能面向声明依赖的插件作者和给 release 打 tag 的 marketplace 维护者。版本约束依赖需要 Claude Code v2.1.110 或更高版本。

怎么工作

在 .claude-plugin/plugin.json 的 dependencies 数组里声明依赖；每个条目要么是裸字符串（仅插件名），要么是带 version 约束的对象。
对象字段：name（插件名，必填）、version（semver 范围，如 ~2.1.0、^2.0、>=1.4、=2.1.0）、marketplace（指定到另一个 marketplace 解析 name）。
version 支持 Node semver 包的所有表达式；预发布版本默认被排除，除非范围用如 ^2.0.0-0 的预发布后缀显式纳入。
版本约束按 marketplace 仓库的 git tag 解析。每个 release 需按 {plugin-name}--v{version} 约定打 tag，从插件目录运行 claude plugin tag --push 自动生成。
安装声明了依赖的插件时，Claude Code 自动解析并安装依赖；依赖若丢失，/reload-plugins 与后台自动更新会重装。
多个已装插件约束同一依赖时，取范围交集，解析到满足全部约束的最高版本；无法合并时报 range-conflict。
跨 marketplace 依赖默认被拒，需根 marketplace 在 marketplace.json 里把目标 marketplace 名加入 allowCrossMarketplaceDependenciesOn 才放行。
启用插件会连带启用其依赖，禁用被其他已启用插件依赖的插件会被拒（需 v2.1.143+）。

怎么配置 / 用法

plugin.json 声明依赖：

json

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

marketplace.json 允许跨 marketplace 依赖：

json

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [ { "name": "audit-logger", "marketplace": "acme-shared" } ]
    }
  ]
}

常用命令：

bash

claude plugin tag --push              # 按 {name}--v{version} 约定打 tag 并推送
claude plugin prune                   # 清理无插件再依赖的孤儿自动安装依赖
claude plugin uninstall deploy-kit --prune  # 卸载并清理其遗留的孤儿依赖
claude plugin list --json             # 读 errors 字段，程序化检查依赖错误

什么时候用

你的插件依赖另一个插件，且需要在上游发布破坏性更新时仍保持可用
希望把依赖锁定在已测试过的版本范围（如 ~2.1.0），按自己的节奏升级
作为 marketplace 维护者发布带独立版本线的多个插件，需要给 release 打 tag 供约束解析
需要依赖另一个 marketplace 的插件，并由根 marketplace 显式授权该跨源信任

限制 / 坑

需要 Claude Code v2.1.110+（版本约束）；连带启用/禁用依赖需 v2.1.143+；claude plugin prune 需 v2.1.121+
tag 解析只适用于 git 后端源；npm marketplace 源的约束不控制抓取哪个版本，仅在加载时校验
来自未添加 marketplace 的依赖不会被解析（保持未解析状态）
多个约束无法取交集、范围非法 semver、或 || 链过于复杂无法求交时，会报 range-conflict 并使插件被禁用
跨 marketplace 依赖若根 marketplace 未在 allowCrossMarketplaceDependenciesOn 列出目标，安装会以 cross-marketplace 错误失败

硬事实速查（12 条）

dependencies 是 .claude-plugin/plugin.json 中的数组，条目可为字符串或 {name, version, marketplace} 对象
version 接受 semver 范围：~2.1.0、^2.0、>=1.4、=2.1.0；按满足范围的最高 tag 版本抓取
tag 命名约定为 {plugin-name}--v{version}，--v 按插件全名前缀匹配，故含连字符的插件名也能正确解析
claude plugin tag 在打 tag 前会校验插件内容、检查版本一致、要求工作区干净、且 tag 不存在
tag 解析出的 semver 与 plugin.json 的 version 分开记录；缓存目录名带 12 位 commit-SHA 后缀
跨 marketplace 授权字段为 allowCrossMarketplaceDependenciesOn，写在根 marketplace 的 marketplace.json，信任不链式传递
约束交集示例：A 要 ^2.0、B 要 >=2.1 → 装满足两者的最高 2.x；A 要 ~2.1、B 要 ~3.0 → B 安装失败 range-conflict
卸载最后一个约束某依赖的插件后，该依赖不再被锁定，下次更新恢复跟随其 marketplace 条目
自动安装的依赖在卸载依赖方后仍留在磁盘，需 claude plugin prune 清理；手动安装的插件永不被 prune
四类依赖错误：dependency-unsatisfied、range-conflict、dependency-version-unsatisfied、no-matching-tag
依赖问题会出现在 claude plugin list、/plugin 界面和 /doctor 中，受影响插件在解决前被禁用
禁用被依赖的插件会被拒，错误会给出按正确顺序链式禁用的命令

官方出处：https://code.claude.com/docs/en/plugin-dependencies

约束插件依赖版本 ​

是什么 ​

怎么工作 ​

怎么配置 / 用法 ​

什么时候用 ​

限制 / 坑 ​