插件市场（创建与分发）

创建并托管 marketplace.json 目录，向团队或社区分发 Claude Code 插件。

是什么

插件市场（plugin marketplace）是一个目录清单，让你把插件分发给他人，提供集中发现、版本追踪、自动更新，并支持多种来源类型（git 仓库、本地路径等）。其核心是仓库根目录下的 .claude-plugin/marketplace.json 文件，列出你的插件及其获取位置。

分发流程包含四步：创建一个或多个插件 → 编写列出插件与来源的 marketplace.json → 推送到 GitHub/GitLab 等 git 主机托管 → 用户用 /plugin marketplace add 添加并安装。市场上线后，推送变更即可更新，用户用 /plugin marketplace update 刷新本地副本。

怎么工作

在仓库根目录创建 .claude-plugin/marketplace.json，包含 name、owner、plugins 三个必填字段。
plugins 数组中每个条目至少需要 name 与 source（插件获取位置）。
source 支持：相对路径（须以 ./ 开头）、github、url（git URL）、git-subdir（git 子目录，稀疏克隆）、npm。
托管到 git（推荐 GitHub）；用户用 /plugin marketplace add owner/repo 添加，或用完整 URL / 本地路径。
安装时 Claude Code 把插件目录复制到缓存 ~/.claude/plugins/cache，因此插件不能引用自身目录之外的文件。
版本解析顺序：plugin.json 的 version → 市场条目的 version → git commit SHA；省略 version 则每次 commit 即为新版本。
用 claude plugin validate . 或 /plugin validate . 校验 JSON 语法与 schema 后再分发。

怎么配置 / 用法

最小 marketplace.json（放在仓库根的 .claude-plugin/ 下）：

json

{
  "name": "company-tools",
  "owner": { "name": "DevTools Team", "email": "devtools@example.com" },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0"
    },
    {
      "name": "deployment-tools",
      "source": { "source": "github", "repo": "company/deploy-plugin" }
    }
  ]
}

常用命令：

shell

/plugin marketplace add ./my-marketplace        # 本地测试
/plugin marketplace add acme-corp/claude-plugins # GitHub owner/repo
/plugin marketplace add acme-corp/claude-plugins@v2.0 # 固定分支/标签
/plugin install quality-review-plugin@my-plugins
/plugin marketplace update [name]               # 刷新
claude plugin validate .                        # 校验

为团队预置（.claude/settings.json）：

json

{
  "extraKnownMarketplaces": {
    "company-tools": { "source": { "source": "github", "repo": "your-org/claude-plugins" } }
  },
  "enabledPlugins": { "code-formatter@company-tools": true }
}

什么时候用

要把多个插件集中分发给团队或社区，提供发现、版本追踪与自动更新。
需要在内部 git/GitHub Enterprise/私有仓库托管并按用户组分发（如 stable / latest 发布通道）。
为容器或 CI 环境预置插件（CLAUDE_CODE_PLUGIN_SEED_DIR），启动即可用、无需运行时克隆。
组织要求严格管控插件来源时，配合 managed settings 的 strictKnownMarketplaces 做白名单。

限制 / 坑

插件被复制到缓存目录，无法引用自身目录外的文件，需用 symlink。
相对路径 source 仅在用户通过 git 添加市场时有效；通过直接 URL 添加 marketplace.json 时相对路径无法解析，须改用 github/npm/git URL 来源。
部分官方市场名（如 claude-code-plugins、anthropic-plugins 等）保留，第三方不可用。
每个用户每个市场名只能注册一个；同名再添加会替换前者。
git 操作默认 120 秒超时，大仓库或慢网络可能失败（可调 CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS）。

硬事实速查（12 条）

市场清单文件路径固定为 .claude-plugin/marketplace.json，位于仓库根目录。
必填字段：name（kebab-case，公开可见，用于 plugin@marketplace）、owner（含必填 name、可选 email）、plugins 数组。
插件条目必填 name 与 source；可选字段含 description、version、author、category、tags、strict 等。
相对路径 source 必须以 ./ 开头，相对于市场根解析，禁止用 ..。
source 类型：相对路径、github(repo/ref?/sha?)、url(url/ref?/sha?)、git-subdir(url/path/ref?/sha?)、npm(package/version?/registry?)。
sha 须为完整 40 字符 git commit SHA；插件 source 支持 ref 与 sha，而市场 source 只支持 ref。
插件下载后复制到本地版本化缓存 ~/.claude/plugins/cache；市场状态记录在 ~/.claude/plugins/known_marketplaces.json（每用户一份）。
版本解析优先级：plugin.json 的 version > 市场条目 version > git commit SHA；避免两处同时设 version。
strict 默认 true（plugin.json 为权威，可被市场条目补充合并）；false 时市场条目即完整定义。
私有仓库手动安装走 git 凭据助手；后台自动更新需设 GITHUB_TOKEN/GH_TOKEN、GITLAB_TOKEN/GL_TOKEN、BITBUCKET_TOKEN 等环境变量。
校验命令 claude plugin validate . 检查 schema、重复插件名、source 路径穿越及与 plugin.json 的版本不一致。
CLI 子命令 claude plugin marketplace add/list/remove(rm)/update 与交互式 /plugin marketplace 等价；add 支持 --scope user|project|local 与 --sparse。

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

插件市场（创建与分发） ​

是什么 ​

怎么工作 ​

怎么配置 / 用法 ​

什么时候用 ​

限制 / 坑 ​