Claude Code 插件市场创建与分发完全指南

本文是对官方文档 Create and distribute a plugin marketplace 的中文要点摘要,完整内容以原文为准。

什么是插件市场

插件市场(plugin marketplace) 是一个插件目录,让你可以把自己编写的 Claude Code 插件集中分发给团队成员或开源社区。它提供:

• 集中发现(centralized discovery)
• 版本追踪(version tracking)
• 自动更新(automatic updates)
• 多来源支持(git 仓库、本地路径等)

如果你只是想从已有市场安装插件,参考官方文档 Discover and install prebuilt plugins。

创建和分发市场的四个步骤

步骤一:准备插件

先确保你已有可分发的插件。插件可包含以下组件类型:

插件创建详见官方文档 Create plugins。

步骤二:编写 marketplace.json

在仓库的 .claude-plugin/ 目录下创建 marketplace.json,定义市场元数据和插件列表。该文件包含三个必填字段:name(市场标识,kebab-case)、owner(维护者信息)和 plugins(插件数组)。基本结构示例：

{
  "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"
      },
      "description": "Deployment automation tools"
    }
  ]
}

每个插件条目至少需要 name 和 source 两个字段,source 告诉 Claude Code 去哪里拉取该插件。

插件来源类型(plugin sources):source 既可以是字符串(相对路径),也可以是带 source 字段做类型判别的对象:

• 相对路径:直接写形如 "./plugins/my-plugin" 的字符串(必须以 ./ 开头),指向市场仓库内的本地目录,相对于市场根目录解析。
• github:对象形式,必填 repo(owner/repo 格式),可选 ref、sha。
• url:对象形式,必填 url(完整 git 仓库地址),可选 ref、sha。
• git-subdir:对象形式,指向 git 仓库内的子目录,必填 url 和 path,可选 ref、sha。
• npm:对象形式,以 npm 包分发,必填 package,可选 version、registry。

对于 git 类来源,可用 ref 锁定分支/tag,用 sha 锁定到精确 commit;两者同时设置时以 sha 为准。

步骤三:托管市场

将包含 .claude-plugin/marketplace.json 的仓库推送到任意 git 托管平台:

• GitHub(文档推荐的方式,自带版本控制、issue 跟踪与团队协作)
• GitLab
• Bitbucket、企业自建 git 服务等

市场本身就是一个普通的 git 仓库,无需特殊服务。使用 GitHub 时用户可用 owner/repo 简写添加;其他平台用完整仓库 URL。推送更新后,用户刷新即可获取最新版本。

步骤四:分享给用户

用户通过以下命令订阅你的市场并安装插件：

# 添加市场(GitHub 可用 owner/repo 简写,也支持 git URL / 本地路径)
/plugin marketplace add <source>

# 安装某个插件
/plugin install <plugin-name>@<marketplace-name>

# 刷新本地市场缓存
/plugin marketplace update

之后用户可以浏览插件列表并按需安装。

版本管理建议

• 使用语义化版本标签(如 v1.2.0)标记稳定版本
• 在插件条目或其 plugin.json 中设置 version 字段以锁定版本;只有该字段变化时用户才会收到更新
• 若省略 version,git 托管市场中的每次新 commit 都会被当作新版本,适合内部或活跃开发的插件
• 在 source 中用 ref 指向具体 tag、用 sha 指向具体 commit,避免默认分支的不稳定变更影响用户

市场维护要点

• 单独维护市场仓库:把 marketplace.json 单独放在一个仓库,而不是混在某个插件仓库里,便于统一管理。
• 写好 README:为订阅者提供明确的安装说明(仓库地址、联系方式等)。
• 插件来源保持可访问:用户安装插件时需要能直接克隆插件来源,私有仓库需额外配置鉴权(凭据助手或 GITHUB_TOKEN 等环境变量)。
• 测试再发布:先用相对路径在本地通过 /plugin marketplace add ./my-marketplace 调试,并用 claude plugin validate . 校验 JSON,再推送到 git 来源。

相关资源