创建并分发插件市场

插件市场是让你向他人分发插件的目录，提供集中式发现、版本追踪、自动更新，并支持多种来源类型。

想从已有市场安装插件？查看发现并安装插件。

概览

创建和分发市场的步骤：

1. 创建插件：构建包含命令、代理、钩子、MCP 服务器或 LSP 服务器的插件
2. 创建市场文件：定义列出插件的 marketplace.json
3. 托管市场：推送到 GitHub、GitLab 或其他 Git 托管
4. 与用户共享：用户通过 /plugin marketplace add 添加并安装插件

演示：创建本地市场

步骤 1：创建目录结构

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

步骤 2：创建技能

---
description: 检查代码中的 Bug、安全问题和性能问题
disable-model-invocation: true
---

检查我选择的代码或最近的变更，关注：
- 潜在 Bug 或边界情况
- 安全问题
- 性能问题
- 可读性改进

步骤 3：创建插件清单

{
  "name": "quality-review-plugin",
  "description": "添加 /quality-review 技能用于快速代码审查",
  "version": "1.0.0"
}

步骤 4：创建市场文件

{
  "name": "my-plugins",
  "owner": {
    "name": "你的名字"
  },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "添加 /quality-review 技能用于快速代码审查"
    }
  ]
}

步骤 5：添加并安装

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

市场文件 Schema

必填字段

字段	类型	说明
name	string	市场标识符（kebab-case，无空格）
owner	object	市场维护者信息，必须包含 name
plugins	array	可用插件列表

保留名称：以下名称保留给 Anthropic 官方使用：claude-code-marketplace、claude-code-plugins、claude-plugins-official、anthropic-marketplace 等。

可选元数据

字段	说明
metadata.description	简短的市场描述
metadata.pluginRoot	相对插件源路径的基础目录

插件来源类型

来源	类型	字段	说明
相对路径	string（如 "./my-plugin"）	—	市场仓库内的本地目录
github	object	repo、ref?、sha?	GitHub 仓库
url	object	url、ref?、sha?	Git URL 来源
git-subdir	object	url、path、ref?、sha?	Git 仓库中的子目录
npm	object	package、version?、registry?	npm 包

GitHub 来源示例

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6..."  // 40 字符 SHA
  }
}

npm 来源示例

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0",
    "registry": "https://npm.example.com"  // 可选私有注册表
  }
}

托管和分发市场

托管在 GitHub（推荐）

1. 创建新仓库
2. 添加 .claude-plugin/marketplace.json
3. 用户通过 /plugin marketplace add owner/repo 添加

托管在其他 Git 服务

/plugin marketplace add https://gitlab.com/company/plugins.git

私有仓库

对于手动安装，Claude Code 使用已有的 git 凭据助手。

对于后台自动更新，设置认证令牌：

提供商	环境变量
GitHub	GITHUB_TOKEN 或 GH_TOKEN
GitLab	GITLAB_TOKEN 或 GL_TOKEN
Bitbucket	BITBUCKET_TOKEN

为容器预填充插件

设置 CLAUDE_CODE_PLUGIN_SEED_DIR 指向预填充目录：

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

种子目录是只读的，不会被写入。自动更新对种子市场禁用。

管理市场限制（企业）

管理员可使用 strictKnownMarketplaces 设置限制用户可添加的市场：

值	行为
未定义（默认）	无限制，用户可添加任何市场
空数组 []	完全锁定，用户无法添加新市场
来源列表	用户只能添加与允许列表完全匹配的市场

仅允许特定市场：

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/approved-plugins" }
  ]
}

通过正则匹配内部 Git 服务器：

{
  "strictKnownMarketplaces": [
    { "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
  ]
}

验证和测试

# 验证市场 JSON 语法
claude plugin validate .

# 在 Claude Code 中验证
/plugin validate .

# 添加并测试
/plugin marketplace add ./path/to/marketplace
/plugin install test-plugin@marketplace-name

版本管理和发布频道

在 plugin.json 中设置版本：

{
  "name": "my-plugin",
  "version": "2.1.0"
}

警告：如果两个 ref 或提交有相同的清单版本，Claude Code 视其为相同并跳过更新。确保每个发布版本有唯一版本号。

故障排除

问题	原因	解决方案
市场无法加载	URL 不可访问	验证 URL 并确认 marketplace.json 存在
相对路径插件在 URL 市场中失败	URL 市场只下载 marketplace.json 本身	改用 Git/GitHub/npm 来源
安装后文件找不到	插件复制到缓存，外部文件引用失效	使用符号链接或重组目录
Git 操作超时	默认 120 秒超时	设置 CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000

相关资源

• 发现并安装插件
• 创建插件
• 插件技术参考
• 插件设置