插件市场(Plugin Marketplace)是分发 Claude Code 插件的标准途径。本文介绍如何从零创建自己的插件市场,并分发给团队或社区。
创建插件市场的四步流程
- 创建插件:包含命令、Agent、Hooks、MCP 服务器或 LSP 服务器的插件(参见 Create plugins 文档)
- 创建 marketplace.json:定义市场目录文件,列出插件及其来源
- 托管市场:推送到 GitHub、GitLab 或其他 Git 托管服务
- 分享给用户:用户通过
/plugin marketplace add添加并安装插件
市场更新后,推送到仓库即可;用户通过 /plugin marketplace update 刷新本地副本。
快速上手:创建本地市场
以下示例创建一个包含 /review 代码审查技能的市场:
# 第一步:创建目录结构
mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/review-plugin/skills/review# 第二步:创建技能文件
# my-marketplace/plugins/review-plugin/skills/review/SKILL.md
---
description: Review code for bugs, security, and performance
disable-model-invocation: true
---
Review the code for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements// 第三步:创建插件清单
// my-marketplace/plugins/review-plugin/.claude-plugin/plugin.json
{
"name": "review-plugin",
"description": "Adds a /review skill for quick code reviews",
"version": "1.0.0"
}// 第四步:创建市场目录文件
// my-marketplace/.claude-plugin/marketplace.json
{
"name": "my-plugins",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "review-plugin",
"source": "./plugins/review-plugin",
"description": "Adds a /review skill for quick code reviews"
}
]
}# 第五步:添加并安装
/plugin marketplace add ./my-marketplace
/plugin install review-plugin@my-pluginsmarketplace.json 完整 Schema
必填字段
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 市场唯一标识(仅字母数字和连字符) |
owner | object | 所有者信息(见下表) |
plugins | array | 插件条目列表 |
Owner 字段
| 字段 | 必填 | 说明 |
|---|---|---|
name | 是 | 所有者名称(个人或组织) |
email | 否 | 联系邮件 |
url | 否 | 官网或文档 URL |
可选元数据
| 字段 | 说明 |
|---|---|
description | 市场简介 |
version | 市场版本(语义化版本) |
homepage | 市场主页 URL |
icon | 市场图标 URL |
keywords | 搜索关键词数组 |
插件条目字段
必填:
| 字段 | 说明 |
|---|---|
name | 插件名称(与 plugin.json 中一致) |
source | 插件来源(见「插件来源类型」) |
可选:
| 字段 | 说明 |
|---|---|
description | 插件简介(覆盖 plugin.json 中的描述) |
version | 锁定版本或范围("1.0.0"、"^1.0.0") |
tags | 标签数组(用于分类和搜索) |
icon | 插件图标 URL |
homepage | 插件主页 URL |
channel | 发布频道(stable/beta/nightly,见「版本与发布频道」) |
插件来源类型(5 种)
1. 相对路径
{ "source": "./plugins/my-plugin" }适合本地市场,路径相对于 marketplace.json 文件所在目录。URL 形式的市场不支持相对路径。
2. GitHub 仓库
{ "source": { "github": "owner/repo" } }
{ "source": { "github": "owner/repo", "ref": "v2.0.0" } } // 锁定版本3. 其他 Git 仓库
{ "source": { "git": "https://gitlab.com/org/plugin.git" } }
{ "source": { "git": "https://gitlab.com/org/plugin.git", "ref": "main" } }4. Git 子目录
{
"source": {
"git": "https://github.com/org/monorepo.git",
"directory": "packages/my-plugin"
}
}5. npm 包
{ "source": { "npm": "@my-org/claude-plugin-name" } }
{ "source": { "npm": "@my-org/plugin", "version": "^2.0.0" } }托管与分发
托管在 GitHub(推荐)
git init my-marketplace
cd my-marketplace
# 创建 .claude-plugin/marketplace.json
git add . && git commit -m "Initial marketplace"
git remote add origin https://github.com/yourname/my-marketplace
git push -u origin main用户添加方式:
/plugin marketplace add yourname/my-marketplace
托管在其他 Git 服务
/plugin marketplace add https://gitlab.com/org/plugins.git
/plugin marketplace add git@gitlab.com:org/plugins.git#v1.0.0
私有仓库
- GitHub 私有仓库:Claude Code 使用
ghCLI 认证(如已安装) - 其他 Git 私有仓库:使用 SSH 密钥或 Git 凭证管理器
- npm 私有包:运行
npm login或配置~/.npmrc
版本与发布频道
// 在 marketplace.json 中为同一插件设置多个频道
{
"plugins": [
{
"name": "my-plugin",
"source": { "github": "org/plugin", "ref": "main" },
"channel": "stable"
},
{
"name": "my-plugin",
"source": { "github": "org/plugin", "ref": "beta" },
"channel": "beta"
}
]
}用户安装指定频道:
/plugin install my-plugin@my-market --channel beta企业市场管理限制(Managed)
管理员可通过 managed-settings.json 控制用户能添加的市场来源:
// 白名单:仅允许公司内部市场
{
"strictKnownMarketplaces": [
{ "source": "official" },
{ "source": "github", "repo": "acme-corp/claude-plugins" }
]
}// 黑名单:屏蔽指定来源(下载前即拦截)
{
"blockedMarketplaces": [
{ "source": "github", "repo": "untrusted/plugins" }
]
}// 自定义信任提示
{
"pluginTrustMessage": "所有来自公司内部市场的插件均已经 IT 部门审核"
}限制规则:strictKnownMarketplaces 为空数组时,禁止添加任何第三方市场(完全锁定)。blockedMarketplaces 优先于 strictKnownMarketplaces(黑名单先生效)。
常见故障排查
| 问题 | 解决方案 |
|---|---|
| 市场无法加载 | 检查 marketplace.json 格式和 git 仓库权限 |
| 市场验证错误 | 确认 name、owner、plugins 字段完整 |
| 插件安装失败 | 检查 source 路径和 git 地址是否正确 |
| 私有仓库认证失败 | 确认 SSH 密钥或 gh CLI 凭证已配置 |
| Git 操作超时 | 检查网络和仓库大小,必要时增加超时配置 |
| URL 市场相对路径失败 | URL 形式的市场不支持相对路径,改用 git/github source |
| 安装后找不到文件 | 确认 directory 字段指向包含 plugin.json 的正确子目录 |
原文:Create and distribute a plugin marketplace - Claude Code Docs | 来源:Anthropic 官方文档