2026 年 2 月 24 日，Anthropic 宣布为 Claude Code 推出私有插件市场，让管理员可以构建、托管和控制插件，而无需接触 Anthropic 的公开注册表。从本文您将获得：捆绑技能并接入可分发插件的确切步骤、在私有 GitHub 仓库中托管、锁定版本，以及诊断第二台机器无法干净安装时最常见的故障。
当团队需要一个插件时
公开市场适合个人实验。一旦有多人依赖同一个斜杠命令或同一个钩子脚本，临时分发方案就会迅速崩溃。有人手动复制文件，使用的路径略有不同，Claude Code 会无声地忽略该钩子，因为名称与注册表期望的不匹配。
这才是私有市场的真正触发点：机器间的一致性，而不是人数。如果你有两名开发者，都需要同一个部署钩子，那么私有市场值得花一小时来设置。如果有二十人，那就不是可选的了。
另一个触发点是保密性。Anthropic 的插件创建文档很明确：要将插件保持在团队内部，需要在私有仓库中托管市场。提交到 claude-community 会将您的插件发布给任何人查看和安装。私有仓库完全避免了这种情况。如果您的插件包含内部 API 模式、专有斜杠命令或任何不希望被索引的内容，私有方案就是正确的选择。
值得注意的是：如果您的团队已在生产环境中运行 MCP 服务器，在确定结构之前，请检查私有插件分发如何与该堆栈配合，因为这两种方法有重叠但不同的用例。
捆绑现有技能和钩子
插件就是一个文件夹。这是最诚实的总结。根据官方插件文档，最小可行结构如下：
my-plugin/
plugin.json
README.md
skills/
my-skill.md
hooks/
hooks.json
guard.sh
plugin.json 是清单。它命名插件、声明版本，并指向技能和钩子子目录。一个精简的示例如下：
{
"name": "deployment-tools",
"version": "1.2.0",
"description": "Deployment workflow helpers for the platform team",
"skills": ["skills/"],
"hooks": "hooks/hooks.json"
}
技能是定义 Claude 知道如何做的事情的 markdown 文件，斜杠命令位于其中。钩子是 JSON 声明，将 shell 脚本连接到触发点（工具调用前、会话后等）。您可以将这两者的任意组合捆绑到一个插件文件夹中。技能文档指出，自定义命令现在是技能模型的一部分，所以不要尝试将其作为单独的并行系统维护。
有一件事经常让人犯错：钩子脚本必须是可执行的。在提交前运行 chmod +x hooks/guard.sh。Claude Code 检查权限位，如果未设置则会无声地跳过钩子。
创建和分发私有市场
市场是一个具有特定文件夹结构的 GitHub 仓库。每个插件都位于自己的子目录中。在仓库根目录下，您需要一个 registry.json 来编目可用内容。插件市场文档详细描述了这个结构，社区演示 mrlm-xyz/demo-claude-marketplace 展示了两个具有代理、命令和技能的工作示例插件，如果您想在从头开始构建前获得具体参考，这会很有帮助。
仓库创建后，在版本库根目录的 .claude/settings.json 中告诉 Claude Code 它的存在：
{
"extraKnownMarketplaces": {
"company-tools": {
"source": {
"source": "github",
"repo": "your-org/claude-plugins"
}
}
},
"enabledPlugins": {
"deployment-tools@company-tools": true,
"code-formatter@company-tools": true
}
}
提交该文件。现在每个信任项目文件夹的团队成员都会自动添加该市场，无需单独提示和无需手动 CLI 步骤。enabledPlugins 块意味着这两个插件默认处于活动状态。任何不想要它们的人都可以在本地禁用；默认设置只是为其他人减少摩擦。
如果你使用团队或企业计划并通过组织设置分发，市场仓库必须是私有或内部的。Claude GitHub App 会读取它，所以你需要明确授予它访问权限。公开仓库在该路径中会无声地失败，这是较为令人困惑的错误模式之一。
对于大规模管理面向客户的 Claude Code 工作的团队，如果你不想自己维护该基础设施，Seahawk 的 Claude Code 代理服务会处理市场设置和持续的插件治理。
控制版本和审查更新
这是大多数私有市场失败的地方。人们在 plugin.json 中固定一个版本，在同一标签下推送破坏性变更，然后想知道为什么回滚不起作用。Git 标签是这里的正确版本真源单位，而不仅仅是清单中的版本字符串。
实际有效的工作流程：
- 更新
plugin.json中的version字段（遵循 semver：从1.2.0到1.3.0表示向后兼容的添加，2.0.0 表示破坏性变更）。 - 提交并推送。
- 创建 git 标签：
git tag v1.3.0 && git push origin v1.3.0。 - 更新
registry.json以将插件条目指向新标签。
在机器上安装特定版本：
/plugin install deployment-tools@company-tools --version 1.3.0
回滚到上一个标签：
/plugin install deployment-tools@company-tools --version 1.2.0
--version 标志根据源仓库中的 git 标签进行解析。如果你还没有标记，Claude Code 会回退到默认分支的 HEAD，这意味着"回滚"没有意义。标记每个版本。这只需要十秒钟，可以省去真正的麻烦。
对于更新审查，将市场仓库视为任何其他生产代码库：至少需要一个拉取请求和一个批准，在合并到 main 前需要在 README.md 中有变更日志条目。Anthropic 自己的文档指出插件是高度受信任的组件，可以执行任意代码，所以不管团队规模多大，插件仓库上一个人可以合并的策略都不是一个好主意。
在第二台机器上测试安装
在告诉更广泛的团队拉取新插件之前，在完全新的配置文件上安装它。不是另一个终端窗口。一个全新的配置文件，没有嵌入的密钥、没有现有的插件状态、没有超出仓库 settings.json 中的预配置市场条目。
清洁第二台机器测试的编号检查清单：
- 克隆项目仓库。
- 打开 Claude Code 并在提示时信任文件夹。
- 用
/plugin marketplace list确认市场出现。 - 显式安装插件：
/plugin install deployment-tools@company-tools。 - 运行插件暴露的斜杠命令，验证它返回预期的输出。
- 通过触发相关工具调用并检查输出来检查钩子是否触发。
- 验证响应中没有出现凭证或开发机器上的本地路径。
最后这个检查很重要。引用绝对路径的钩子脚本（/Users/yourname/scripts/...）在其他每台机器上都会中断。使用相对于插件目录的路径或团队可以一致设置的环境变量。
排查名称、路径和依赖问题
大多数安装失败属于三类之一。
名称不匹配。plugin.json 中的插件名称必须与市场仓库中的目录名称和 registry.json 中使用的名称完全匹配。区分大小写。如果 plugin.json 说的是 deployment-tools，而注册表条目说的是 Deployment-Tools，安装命令会返回一个看起来与大小写无关的未找到错误。
钩子中的路径问题。如上所述，绝对路径是"在我的机器上可以工作"类错误的最大根源。在标记发布前，审查钩子脚本中的每个硬编码路径。一个快速的 grep -r "/Users" hooks/ 会捕捉最常见的情况。
依赖缺口。如果钩子脚本调用外部二进制文件（jq、gh、docker、自定义内部 CLI），在 README.md 中记录该依赖及其最低版本。Claude Code 不会为你解析外部二进制依赖。因为 jq 未安装而静默退出的钩子很难诊断，特别是对于不知道该钩子存在的团队成员。
安装停滞时还有其他几个值得检查的事项：
- GitHub App 需要对私有市场仓库的读取权限。如果获取挂起，检查组织设置。
- 如果
extraKnownMarketplaces在settings.json中但信任文件夹后市场未出现，确认文件已提交并且接受了信任提示，而不是被驳回。 enabledPlugins中的插件名称必须精确使用name@marketplace格式。单独的deployment-tools无法在没有市场限定符的情况下解析。
Nagell 的 dev.to 系列深入介绍了自动版本化和发布 CI，如果你想将 GitHub Actions 纳入标记工作流，值得在手动构建 CI 步骤前阅读。
要了解 Claude Code 如何超越单独插件融入真实开发工作流的更广泛背景，这份 Claude Code 超能力概览很有用。
FAQ
我可以在 GitHub 以外的地方托管市场吗？
settings.json 中的 source 字段根据当前插件市场文档支持 github 和 local 作为源类型。本地路径适用于单台机器或挂载的网络共享，但它不会像 git 支持的源那样自动更新。为了实现具有版本跟踪的团队分发，私有 GitHub 仓库是目前的实际选择。
团队成员需要自己的 GitHub 访问权限来访问私有市场仓库吗？
不需要直接访问。如果你在团队或企业计划的组织设置中分发，Claude GitHub App 会代表他们读取仓库。如果你在 settings.json 中使用 extraKnownMarketplaces 而不经过组织同步路径，每个用户需要通过自己的 GitHub 凭证或部署密钥读取仓库。
`enabledPlugins` 和实际安装插件之间有什么区别？
settings.json 中的 enabledPlugins 在项目文件夹被信任时自动激活插件。这是默认值，不是强制安装。用户仍然可以在本地禁用插件。通过 /plugin install 手动安装会添加插件，无论 settings.json 说什么。两种机制一起工作：默认值用于便利，手动安装用于项目上下文之外的任何内容。
我可以在一个组织中有多个私有市场吗？
可以。extraKnownMarketplaces 对象接受多个键。每个键是本地市场别名，每个都指向单独的源仓库。你可以在同一个 settings.json 中注册 company-tools、data-team-plugins 和 security-tools。只需确保别名唯一，不会与 claude-plugins-official 或 claude-community 冲突。
这如何与 Anthropic 的官方marketplace交互?
两者共存。Claude Code 在首次交互启动时自动注册 claude-plugins-official。你的私有marketplace与其并行运作。来自私有marketplace的插件被引用为 plugin-name@your-alias；官方插件为 plugin-name@claude-plugins-official。不会有冲突，只要你的插件名称不与官方插件重复而造成解析歧义。
这一切中最严厉的警告：git标签是唯一可靠的回滚机制。plugin.json中没有配对标签的版本字符串只是装饰，不是恢复选项。