Claude Code 插件市场开发及注意事项

一、项目结构

复制代码

├── .claude-plugin/
│   └── marketplace.json            # 市场定义（唯一必需的配置文件）
├── plugins/
│   ├── plugin-a/                   # 插件 A
│   │   ├── .claude-plugin/plugin.json
│   │   ├── hooks/
│   │   ├── scripts/
│   │   └── skills/
│   ├── plugin-b/                   # 插件 B
│   └── plugin-c/                   # 插件 C
└── dist/                           # 打包输出目录

核心要点： 一个 Git 仓库可以包含多个插件，每个插件放在 plugins/ 下的独立子目录中。

二、关键文件说明

marketplace.json

市场只需要一个配置文件：.claude-plugin/marketplace.json。

json 复制代码

{
  "name": "my-marketplace",
  "plugins": [
    {
      "name": "plugin-a",
      "source": "./plugins/plugin-a",
      "description": "插件描述",
      "version": "0.0.1"
    }
  ]
}

source 使用相对路径即可，无论本地安装还是远程安装都适用
不需要 额外创建 marketplace-remote.json，Claude Code 会先 clone 仓库再解析相对路径

plugin.json

每个插件必须有 .claude-plugin/plugin.json，定义插件的元信息。

三、安装方式

用户安装流程（两步）

bash 复制代码

# 1. 添加市场源（一次性）
/plugin marketplace add git@your-git-server.com:org/marketplace-repo.git

# 2. 安装具体插件
/plugin install plugin-a@my-marketplace

本地开发调试

bash 复制代码

/plugin marketplace add /path/to/local/marketplace-repo
/plugin install plugin-a@my-marketplace

四、git-subdir 机制

当用户通过 Git URL 添加市场后，安装插件时 Claude Code 使用 git-subdir 机制：

clone 整个仓库到本地缓存
定位到插件子目录 （如 plugins/plugin-a）
提取该子目录作为插件内容安装

这就是"一个仓库、多个插件"能工作的原因。

五、SSH vs HTTPS 踩坑记录

问题现象

协议	marketplace add	plugin install
HTTPS	❌ 认证失败（内网 Git 平台不支持匿名 HTTPS）	-
SSH	✅ 成功	❌ 报错：地址被转换为错误的 HTTP URL

根因分析

Claude Code 在处理 git-subdir 源时，会内部将 SSH 地址转换为 HTTP 地址进行 clone。如果内网 Git 平台的 HTTP 服务返回了重定向或格式不兼容，就会导致 clone 失败。

转换链路：

复制代码

git@server.com:org/repo.git
    ↓ Claude Code 内部 SSH→HTTP 转换
http://server.com/org/repo.git
    ↓ 平台 HTTP 重定向
http://other-domain.com/path/org/repo.git  ← 不可用

解决方案

利用 Git 的 insteadOf URL 重写机制，将错误的 HTTP 地址拦截并替换回 SSH。

语法结构：

ini 复制代码

[url "<替换后的前缀>"]
    insteadOf = <要被替换的前缀>

示例：

bash 复制代码

git config --global url."git@your-git-server.com:".insteadOf "http://redirected-domain.com/path/"

原理： Git 在发起网络请求前，会先检查 URL 是否匹配 insteadOf 规则，匹配则做前缀替换：

复制代码

输入:  http://redirected-domain.com/path/org/repo.git
匹配:  http://redirected-domain.com/path/
替换为: git@your-git-server.com:
结果:  git@your-git-server.com:org/repo.git  ← 走 SSH，正常工作

注意事项

这条 insteadOf 规则需要每个团队成员都配置一次
建议写入 README 的前置配置步骤中
只做前缀替换，后面的路径部分原样保留

六、常见问题

Q: marketplace.json 和 marketplace-remote.json 都需要吗？

不需要。 只保留 marketplace.json 即可。Claude Code 通过 Git URL 添加市场时，会先 clone 仓库，然后读取 marketplace.json，其中的相对路径会基于 clone 后的本地目录解析。

Q: HTTPS 认证失败怎么办？

如果内网 Git 平台不支持匿名 HTTPS clone，直接使用 SSH 地址 + insteadOf 配置方案。

Q: 更新插件后用户如何获取最新版？

将代码 push 到 Git 仓库后，用户重新执行 /plugin install 即可拉取最新版本。

七、发布 Checklist

✅ 插件目录下有 .claude-plugin/plugin.json
✅ marketplace.json 中已注册该插件
✅ 代码已 push 到远程 Git 仓库
✅ README 中包含前置配置说明（如需要 insteadOf）
✅ 团队成员已配置 Git URL 重写规则