教程

Claude Code 插件市场创建与分发:marketplace.json 完整 Schema、私有仓库与企业限制

Claude Code 插件市场创建与分发完整指南:四步创建流程(插件/marketplace.json/Git 托管/分享用户)、快速上手本地市场示例(/review 代码审查技能)、marketplace.json 完整 Schema(必填/Owner/可选元数据/插件条目)、五种插件来源类型(相对路径/GitHub/Git/子目录/npm)、托管分发(GitHub 推荐/私有仓库认证)、版本与发布频道配置(stable/beta/nightly)、企业 Managed 限制(strictKnownMarketplaces 白名单/blockedMarketplaces 黑名单/pluginTrustMessage),以及七大常见故障排查。

2026/3/76分钟 阅读ClaudeEagle

插件市场(Plugin Marketplace)是分发 Claude Code 插件的标准途径。本文介绍如何从零创建自己的插件市场,并分发给团队或社区。

创建插件市场的四步流程

  1. 创建插件:包含命令、Agent、Hooks、MCP 服务器或 LSP 服务器的插件(参见 Create plugins 文档)
  2. 创建 marketplace.json:定义市场目录文件,列出插件及其来源
  3. 托管市场:推送到 GitHub、GitLab 或其他 Git 托管服务
  4. 分享给用户:用户通过 /plugin marketplace add 添加并安装插件

市场更新后,推送到仓库即可;用户通过 /plugin marketplace update 刷新本地副本。

快速上手:创建本地市场

以下示例创建一个包含 /review 代码审查技能的市场:

bash
# 第一步:创建目录结构
mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/review-plugin/skills/review
markdown
# 第二步:创建技能文件
# 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
json
// 第三步:创建插件清单
// 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"
}
json
// 第四步:创建市场目录文件
// 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"
    }
  ]
}
bash
# 第五步:添加并安装
/plugin marketplace add ./my-marketplace
/plugin install review-plugin@my-plugins

marketplace.json 完整 Schema

必填字段

字段类型说明
namestring市场唯一标识(仅字母数字和连字符)
ownerobject所有者信息(见下表)
pluginsarray插件条目列表

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. 相对路径

json
{ "source": "./plugins/my-plugin" }

适合本地市场,路径相对于 marketplace.json 文件所在目录。URL 形式的市场不支持相对路径。

2. GitHub 仓库

json
{ "source": { "github": "owner/repo" } }
{ "source": { "github": "owner/repo", "ref": "v2.0.0" } }  // 锁定版本

3. 其他 Git 仓库

json
{ "source": { "git": "https://gitlab.com/org/plugin.git" } }
{ "source": { "git": "https://gitlab.com/org/plugin.git", "ref": "main" } }

4. Git 子目录

json
{
  "source": {
    "git": "https://github.com/org/monorepo.git",
    "directory": "packages/my-plugin"
  }
}

5. npm 包

json
{ "source": { "npm": "@my-org/claude-plugin-name" } }
{ "source": { "npm": "@my-org/plugin", "version": "^2.0.0" } }

托管与分发

托管在 GitHub(推荐)

bash
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 使用 gh CLI 认证(如已安装)
  • 其他 Git 私有仓库:使用 SSH 密钥或 Git 凭证管理器
  • npm 私有包:运行 npm login 或配置 ~/.npmrc

版本与发布频道

json
// 在 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"
    }
  ]
}

用户安装指定频道:

bash
/plugin install my-plugin@my-market --channel beta

企业市场管理限制(Managed)

管理员可通过 managed-settings.json 控制用户能添加的市场来源:

json
// 白名单:仅允许公司内部市场
{
  "strictKnownMarketplaces": [
    { "source": "official" },
    { "source": "github", "repo": "acme-corp/claude-plugins" }
  ]
}
json
// 黑名单:屏蔽指定来源(下载前即拦截)
{
  "blockedMarketplaces": [
    { "source": "github", "repo": "untrusted/plugins" }
  ]
}
json
// 自定义信任提示
{
  "pluginTrustMessage": "所有来自公司内部市场的插件均已经 IT 部门审核"
}

限制规则strictKnownMarketplaces 为空数组时,禁止添加任何第三方市场(完全锁定)。blockedMarketplaces 优先于 strictKnownMarketplaces(黑名单先生效)。

常见故障排查

问题解决方案
市场无法加载检查 marketplace.json 格式和 git 仓库权限
市场验证错误确认 nameownerplugins 字段完整
插件安装失败检查 source 路径和 git 地址是否正确
私有仓库认证失败确认 SSH 密钥或 gh CLI 凭证已配置
Git 操作超时检查网络和仓库大小,必要时增加超时配置
URL 市场相对路径失败URL 形式的市场不支持相对路径,改用 git/github source
安装后找不到文件确认 directory 字段指向包含 plugin.json 的正确子目录

原文:Create and distribute a plugin marketplace - Claude Code Docs | 来源:Anthropic 官方文档

相关文章推荐

教程Claude Code 模型配置完全指南:opusplan 混合模式、effort 级别、1M 上下文与第三方 Model 固定Claude Code 模型配置完全指南:6 个模型别名(default/sonnet/opus/haiku/sonnet[1m]/opusplan 混合模式)、四种设置优先级(/model 会话 > --model 启动 > ANTHROPIC_MODEL 环境变量 > settings.json)、default 按账号类型说明(Max/Team Premium 默认 Opus/Pro/Standard 默认 Sonnet)、opusplan 规划执行混合模式原理、三级 Effort 级别(low/medium/high 及自适应推理关闭方式)、1M Token 上下文(Beta 可用性/200K 计费门槛/DISABLE_1M_CONTEXT 禁用)、企业 availableModels 白名单、四个模型别名环境变量,以及第三方部署(Bedrock/Vertex/Foundry)固定版本的重要操作和升级流程。2026/3/9教程Claude Code 插件开发指南:plugin.json 结构、Skills/Hooks/MCP 集成与官方市场提交Claude Code 插件开发完整指南:独立配置 vs 插件对比(命名空间/适用场景)、5 步快速创建(目录/plugin.json 清单字段/Skill/本地 --plugin-dir 测试/分享)、完整插件目录结构(.claude-plugin/commands/skills/agents/hooks/mcp/.lsp.json/settings.json)、各组件配置示例(Skills SKILL.md/LSP 服务器.lsp.json/默认 settings.json agent 键)、从独立配置迁移步骤对比表、三步调试方法,以及通过 claude.ai 和 Console 提交官方市场的方式。2026/3/8教程Claude Code Server-managed Settings(Beta):无 MDM 企业集中配置、安全审批与缓存机制Claude Code Server-managed Settings(Beta)完整指南:适用场景(无 MDM/非受管设备)、前提条件(Teams≥2.1.38/Enterprise≥2.1.30/api.anthropic.com 网络)、与 Endpoint-managed 对比选择、设置下发机制(启动抓取+每小时轮询/首次启动短暂窗口期/缓存网络故障保持)、三类安全审批对话框(Shell 命令/自定义环境变量/Hook 配置)、Owner 角色访问控制、Beta 限制(不支持分组/不支持 MCP 配置)、各提供商平台可用性(Bedrock/Vertex/Foundry 不可用),以及五种边界场景行为表和 ConfigChange Hook 加强方案。2026/3/7教程Claude Code settings.json 完整配置参考:40+ 配置项、作用域继承与插件管理Claude Code settings.json 完整配置参考:四级作用域(Managed 最高不可覆盖/User/Project/Local)及其优先级继承规则、不同功能的配置文件位置(Settings/Subagents/MCP/Plugins/CLAUDE.md)、40+ 配置项速查(基础/认证/界面/工作流/权限/安全企业/MCP/插件),包括 companyAnnouncements 公告、apiKeyHelper 动态 Key、fastModePerSessionOptIn 会话级快速模式、strictKnownMarketplaces 市场限制,以及 /config 命令和验证方法。2026/3/7教程Claude Code OpenTelemetry 监控指南:六步快速配置、8 类指标与 5 类事件 Schema 完整参考Claude Code OpenTelemetry 监控完整指南:六步快速启动(TELEMETRY/EXPORTER/端点/认证/调试间隔)、管理员 MDM 托管集中配置、完整环境变量(核心/独立信号/隐私控制/基数控制/mTLS)、8 类指标(session/lines_of_code/PR/commit/cost/token/code_edit_decision/active_time)、5 类事件(user.prompt/tool.result/api.request/api.error/tool.decision)、动态 Headers 脚本(29 分钟刷新)和 Grafana 成本告警示例。2026/3/7教程Claude Code 插件开发指南:从 plugin.json 到 Skills/Agents/Hooks 打包发布全流程Claude Code Plugin 开发完整指南:独立配置 vs Plugin 选型(短名称 vs 命名空间)、5 分钟创建第一个 Plugin(plugin.json Manifest + SKILL.md)、Plugin 目录结构(skills/agents/hooks/settings/lsp)、LSP 服务器集成、随 Plugin 发布默认 Hooks 设置、--plugin-dir 本地测试、从独立配置迁移(名称变化说明)、Git/npm 发布方式,以及 /plugin install/list/enable/disable/remove 用户命令。2026/3/6