插件市场（plugin marketplace）是一个可共享的插件目录，支持集中发现、版本追踪和自动更新。本文从零搭建完整流程：编写 marketplace.json（必填字段、来源类型、strict 模式），托管到 Git 服务，容器预填充（CLAUDE_CODE_PLUGIN_SEED_DIR），企业管控（strictKnownMarketplaces）以及 CLI 管理命令。想安装现有市场的插件？见发现并安装插件。

Claude Code 插件市场创建与分发 #

概览 #

创建和分发插件市场分四步：

1. 创建插件：构建包含 skills、agents、hooks、MCP 服务器或 LSP 服务器的插件。本文假设你已有待分发的插件；创建插件详见创建插件。
2. 创建市场文件：定义 marketplace.json，列出插件及其来源（见创建市场文件）。
3. 托管市场：推送到 GitHub、GitLab 或其他 Git 托管服务（见托管与分发）。
4. 与用户共享：用户用 /plugin marketplace add 添加市场，然后安装单个插件（见发现并安装插件）。

市场上线后，推送变更即可更新。用户运行 /plugin marketplace update 刷新本地副本。

演示：创建本地市场 #

本示例创建一个包含单个插件（quality-review 技能，用于代码审查）的市场。

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. 创建技能文件

# my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md
---
description: Review code for bugs, security, and performance
disable-model-invocation: true
---

Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements

Be concise and actionable.

3. 创建插件清单

# my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json
{
  "name": "quality-review-plugin",
  "description": "Adds a quality-review skill for quick code reviews",
  "version": "1.0.0"
}

设置 version 后，用户仅在该字段变更时收到更新。每次发布需更新版本号。省略 version 且市场托管在 git 中时，每次提交都算作新版本。参见版本解析与发布频道。

4. 创建市场目录

# my-marketplace/.claude-plugin/marketplace.json
{
  "name": "my-plugins",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Adds a quality-review skill for quick code reviews"
    }
  ]
}

5. 添加并安装

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

6. 使用技能

选择代码后运行：

/quality-review-plugin:quality-review

关于插件更完整的能力（hooks、agents、MCP 服务器、LSP 服务器），参见插件。

插件安装机制：安装时 Claude Code 将插件目录复制到缓存位置。插件不能通过 ../shared-utils 等方式引用目录外的文件，因为那些文件不会被复制。如需跨插件共享文件，使用符号链接。参见插件缓存与文件解析。

创建市场文件 #

在仓库根目录创建 .claude-plugin/marketplace.json。该文件定义市场名称、维护者信息和插件列表。每个插件条目至少需要 name 和 source（来源）。完整 schema 见Marketplace schema。

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

Marketplace schema #

必填字段 #

保留名称：以下市场名称已被 Anthropic 官方占用，第三方市场不可使用：claude-code-marketplace、claude-code-plugins、claude-plugins-official、anthropic-marketplace、anthropic-plugins、agent-skills、anthropic-agent-skills、knowledge-work-plugins、life-sciences、claude-for-legal、claude-for-financial-services、financial-services-plugins。仿冒官方市场的名称（如 official-claude-plugins、anthropic-tools-v2）也被封禁。

Owner 字段 #

可选字段 #

description 和 version 也可放在 metadata 下（向后兼容）。

插件条目 #

plugins 数组中的每个条目描述一个插件及其来源。可包含插件清单 schema 中的任意字段（如 description、version、author、commands、hooks 等），以及市场特有字段：source、category、tags、strict。

必填字段 #

可选插件字段 #

标准元数据字段：

组件配置字段：

插件来源 #

插件来源告诉 Claude Code 从哪里获取每个插件。一旦克隆或复制到本地机器，插件会被复制到本地版本化插件缓存 ~/.claude/plugins/cache。

市场来源 vs 插件来源：两者是不同的概念，控制不同的事物。

• 市场来源：获取 marketplace.json 目录本身的位置。用户运行 /plugin marketplace add 时设置，或在 extraKnownMarketplaces 中配置。支持 ref（分支/标签）但不支持 sha。
• 插件来源：市场中每个插件的位置。在 marketplace.json 中每个插件条目的 source 字段设置。支持 ref 和 sha（精确 commit）。

例如，托管在 acme-corp/plugin-catalog（市场来源）的市场可以列出来自 acme-corp/code-formatter（插件来源）的插件。两者指向不同的仓库，可独立锁定。

相对路径 #

对于同一仓库内的插件，使用以 ./ 开头的路径：

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

路径相对于市场根目录（包含 .claude-plugin/ 的目录）。上例中 ./plugins/my-plugin 指向 <repo>/plugins/my-plugin，即使 marketplace.json 位于 <repo>/.claude-plugin/marketplace.json。不要使用 ../ 引用市场根目录外的路径。

相对路径仅在用户通过 Git（GitHub、GitLab 或 git URL）添加市场时有效。若用户通过直接指向 marketplace.json 文件的 URL 添加市场，相对路径无法正确解析。对于 URL 分发方式，请改用 GitHub、npm 或 git URL 来源。参见故障排查。

GitHub 仓库 #

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

可锁定到特定分支、标签或提交：

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Git 仓库（通用） #

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

可锁定到特定分支、标签或提交：

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Git 子目录 #

git-subdir 用于插件位于 Git 仓库子目录的场景。Claude Code 使用稀疏部分克隆仅获取该子目录，最小化带宽消耗，适合大型 monorepo。

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

可锁定到特定版本：

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

url 也接受 GitHub 简写（owner/repo）或 SSH URL（git@github.com:owner/repo.git）。

npm 包 #

通过 npm install 安装。适用于公共 npm registry 或团队私有的 registry。

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

锁定版本：

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

使用私有 registry：

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

高级插件条目示例 #

以下示例使用了多个可选字段，包括 commands、agents、hooks、MCP 服务器的自定义路径：

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@example.com"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

关键要点：

• commands 和 agents：可以指定多个目录或单个文件。路径相对于插件根目录。
• ${CLAUDE_PLUGIN_ROOT}：在 hooks 和 MCP 服务器配置中引用插件安装目录内的文件。由于插件安装时会复制到缓存位置，必须使用此变量。对于需要在插件更新后持久化的依赖或状态，使用 ${CLAUDE_PLUGIN_DATA} 代替。
• strict: false：插件不需要自己的 plugin.json，市场条目定义了全部内容。参见 Strict 模式。

Strict 模式 #

strict 字段控制 plugin.json 是否为组件定义（skills、agents、hooks、MCP 服务器、输出样式）的权威来源。

使用场景：

• strict: true：插件有自己的 plugin.json 并管理自身组件。市场条目可在其上添加额外的 skills 或 hooks。这是默认行为，适合大多数插件。
• strict: false：市场运营者想要完全控制。插件仓库提供原始文件，市场条目定义哪些文件作为 skills、agents、hooks 等暴露。适合市场需要重新组织或策划插件组件的场景。

托管与分发 #

托管在 GitHub（推荐） #

1. 创建仓库：为你的市场设置一个新仓库
2. 添加市场文件：创建 .claude-plugin/marketplace.json
3. 与团队共享：用户通过 /plugin marketplace add owner/repo 添加

优势：内置版本控制、issue 追踪和团队协作。

托管在其他 Git 服务 #

任何 Git 托管服务均可（GitLab、Bitbucket、自托管服务器）。用户用完整仓库 URL 添加：

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

私有仓库 #

Claude Code 支持从私有仓库安装插件。手动安装和更新时，Claude Code 使用你已有的 git 凭据助手，因此通过 gh auth login、macOS Keychain 或 git-credential-store 的 HTTPS 访问与终端中一样有效。SSH 访问要求主机已在 known_hosts 中且密钥已加载到 ssh-agent 中（因为 Claude Code 会抑制交互式 SSH 提示，包括主机指纹和密钥密码）。

后台自动更新在启动时运行，无法使用凭据助手（因为交互式提示会阻塞启动）。要为私有市场启用自动更新，请在环境中设置相应的认证令牌：

在 shell 配置文件（如 .bashrc、.zshrc）中设置，或运行 Claude Code 时传入：

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

对于 CI/CD 环境，将令牌配置为秘密环境变量。GitHub Actions 会自动为同一组织中的仓库提供 GITHUB_TOKEN。

本地测试后再分发 #

在分享前先本地测试：

/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace

关于完整的添加命令（GitHub、Git URL、本地路径、远程 URL），参见添加市场。

为团队配置必装市场 #

可以在项目仓库中配置，以便团队成员在信任项目文件夹时自动收到安装市场的提示。将市场添加到项目根目录的 .claude/settings.json：

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

还可以指定默认启用的插件：

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

完整配置选项参见插件设置。

如果使用相对路径的本地 directory 或 file 来源，路径相对于仓库的主检出（main checkout）。从 git worktree 运行 Claude Code 时，路径仍指向主检出，因此所有 worktree 共享同一市场位置。市场状态每个用户存储一次在 ~/.claude/plugins/known_marketplaces.json 中，并非按项目存储。

容器预填充插件 #

对于容器镜像和 CI 环境，可以在构建时预填充插件目录，使 Claude Code 启动时无须克隆即可使用市场和插件。设置环境变量 CLAUDE_CODE_PLUGIN_SEED_DIR 指向此目录。

要叠加多个种子目录，Unix 上用 : 分隔路径，Windows 上用 ;。Claude Code 按顺序搜索每个目录，第一个包含给定市场或插件缓存的种子胜出。

种子目录镜像 ~/.claude/plugins 的结构：

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

构建种子目录：在镜像构建期间运行一次 Claude Code，安装所需插件，然后将生成的 ~/.claude/plugins 目录复制到镜像中，并让 CLAUDE_CODE_PLUGIN_SEED_DIR 指向它。

要跳过复制步骤，在构建期间设置 CLAUDE_CODE_PLUGIN_CACHE_DIR 为目标种子路径，使插件直接安装到该目录：

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

然后在容器运行时环境中设置 CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed，使 Claude Code 启动时从种子读取。

启动时，Claude Code 将种子 known_marketplaces.json 中的市场注册到主配置，并使用 cache/ 下的插件缓存而不重新克隆。这在交互模式和非交互模式（使用 -p 标志）下均有效。

行为细节：

• 只读：种子目录永远不会被写入。种子市场的自动更新被禁用，因为 git pull 在只读文件系统上会失败。
• 种子条目优先：每次启动时，种子中声明的市场会覆盖用户配置中的任何匹配条目。要禁用种子插件，使用 /plugin disable 而不是移除市场。
• 路径解析：Claude Code 通过在运行时探测 $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ 来定位市场内容，不依赖种子 JSON 内存储的路径。即使种子挂载到与构建时不同的路径，也能正常工作。
• 禁止修改：对种子管理的市场运行 /plugin marketplace remove 或 /plugin marketplace update 会失败，并提示联系管理员更新种子镜像。
• 与 settings 组合：如果 extraKnownMarketplaces 或 enabledPlugins 声明的市场已存在于种子中，Claude Code 使用种子副本，不进行克隆。

企业管控：受管理的市场限制 #

对于需要严格控制插件来源的组织，管理员可以使用托管设置中的 strictKnownMarketplaces 限制用户允许添加的插件市场。

当托管设置中配置了 strictKnownMarketplaces 时，限制行为取决于该值：

常见配置 #

禁止所有市场添加：

{
  "strictKnownMarketplaces": []
}

只允许特定市场：

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    }
  ]
}

通过正则模式匹配主机名来允许内部 Git 服务器的所有市场（推荐用于 GitHub Enterprise Server 或自托管 GitLab）：

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

通过正则模式匹配路径来允许来自特定目录的文件系统市场：

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

使用 ".*" 作为 pathPattern 可允许任意文件系统路径，同时通过 hostPattern 控制网络来源。

strictKnownMarketplaces 限制用户能添加什么，但不会自行注册市场。要使允许的市场自动可用（无需用户运行 /plugin marketplace add），请将其与同一 managed-settings.json 中的 extraKnownMarketplaces 配合使用。参见同时使用两者。

限制机制 #

限制在操作任何网络或文件系统之前检查。检查在市场添加、插件安装、更新、刷新和自动更新时运行。如果市场在配置策略之前已添加，且其来源不再匹配白名单，Claude Code 将拒绝从该市场安装或更新插件。相同的执行机制也适用于 blockedMarketplaces。

白名单使用精确匹配（大多数来源类型）。对于市场被允许，所有指定的字段必须完全匹配：

• 对于 GitHub 来源：repo 是必需的，如果白名单中指定了 ref 或 path，也必须匹配
• 对于 URL 来源：完整 URL 必须完全匹配
• 对于 hostPattern 来源：市场主机名与正则模式匹配
• 对于 pathPattern 来源：市场的文件系统路径与正则模式匹配

精确匹配不规范化 URL：尾部斜杠、.git 后缀或 ssh:// 与 https:// 形式被视为不同的值。如果组织的市场可以通过多种 URL 形式克隆，最好使用 hostPattern 条目而不是字面 URL，以便所有形式都匹配。

由于 strictKnownMarketplaces 设置在托管设置中，单个用户和项目配置无法覆盖这些限制。

完整的配置细节（包括所有支持的来源类型和与 extraKnownMarketplaces 的比较）参见 strictKnownMarketplaces 参考。

版本解析与发布频道 #

插件版本决定缓存路径和更新检测：如果解析出的版本与用户已拥有的版本匹配，/plugin update 和自动更新会跳过该插件。

Claude Code 按以下优先顺序解析插件版本：

1. plugin.json 中的 version
2. 市场条目中的 version
3. 插件来源的 git commit SHA

对于基于 Git 的来源类型（github、url、git-subdir 以及 Git 托管市场内的相对路径），可以完全省略 version，每个新提交都被视为新版本。这是内部或活跃开发插件最简单的设置。

设置 version 会锁定插件。如果 plugin.json 声明了 "version": "1.0.0"，推送新提交而不更改字符串对现有用户没有影响，因为 Claude Code 看到相同版本并保持缓存副本。每次发布都要更新该字段，或者省略它以使用 commit SHA。

避免同时在 plugin.json 和市场条目中设置 version。plugin.json 的值总是静默胜出，因此过时的清单版本可能掩盖你在 marketplace.json 中设置的版本。

设置发布频道 #

为了支持插件的 “stable” 和 “latest” 发布频道，可以设置两个不同的市场，指向同一仓库的不同 ref 或 SHA。然后通过托管设置将两个市场分配给不同的用户组。

每个频道必须解析为不同的版本。如果使用显式版本，plugin.json 必须在每个锁定的 ref 处声明不同的 version。如果省略 version，不同的 commit SHA 本身就足以区分频道。如果两个 ref 解析为相同的版本字符串，Claude Code 视它们为相同并跳过更新。

示例 #

// stable-tools 市场
{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}

// latest-tools 市场
{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}

分配频道给用户组 #

通过托管设置将每个市场分配给相应的用户组。例如，稳定组收到：

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

早期访问组收到 latest-tools：

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

锁定依赖版本 #

插件可以将其依赖限制在 semver 范围内，以防止依赖更新破坏插件。参见约束插件依赖版本了解 {plugin-name}--v{version} git-tag 约定、范围语法以及同一依赖上的多个约束如何组合。

验证与测试 #

在分发前测试你的市场。

验证市场 JSON 语法：

claude plugin validate .

或在 Claude Code 内部运行：

/plugin validate .

添加市场进行测试：

/plugin marketplace add ./path/to/marketplace

安装测试插件验证一切正常：

/plugin install test-plugin@marketplace-name

完整的插件测试工作流参见本地测试插件。技术故障排查参见插件参考。

CLI 管理市场 #

Claude Code 提供了非交互式的 claude plugin marketplace 子命令，适用于脚本和自动化。这些命令与交互式会话中的 /plugin marketplace 命令等效。

添加市场 #

claude plugin marketplace add <source> [options]

参数：

• <source>：GitHub owner/repo 简写、git URL、远程 URL（指向 marketplace.json 文件）或本地目录路径。要锁定到分支或标签，在 GitHub 简写后追加 @ref，在 git URL 后追加 #ref。

选项：

从 GitHub 添加：

claude plugin marketplace add acme-corp/claude-plugins

锁定到分支或标签：

claude plugin marketplace add acme-corp/claude-plugins@v2.0

从非 GitHub 的主机添加：

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

从直接提供 marketplace.json 的远程 URL 添加：

claude plugin marketplace add https://example.com/marketplace.json

从本地目录测试：

claude plugin marketplace add ./my-marketplace

在项目范围声明市场（通过 .claude/settings.json 与团队共享）：

claude plugin marketplace add acme-corp/claude-plugins --scope project

对于 monorepo，限制检出只包含插件内容的目录：

claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

列出市场 #

claude plugin marketplace list [options]

选项：

移除市场 #

claude plugin marketplace remove <name>

参数：

• <name>：要移除的市场名称（由 claude plugin marketplace list 显示）。这是 marketplace.json 中的 name，不是添加时使用的来源。

移除市场也会卸载所有从该市场安装的插件。要刷新市场而不丢失已安装的插件，使用 claude plugin marketplace update。

更新市场 #

claude plugin marketplace update [name]

参数：

• [name]：要更新的市场名称（由 claude plugin marketplace list 显示）。省略则更新所有市场。

remove 和 update 在对种子管理市场运行时都会失败，因为种子市场是只读的。更新所有市场时，种子管理条目被跳过，其他市场仍然更新。要更改种子提供的插件，请联系管理员更新种子镜像。参见容器预填充插件。

故障排查 #

市场加载失败 #

症状：无法添加市场或看到其中的插件

解决方案：

• 验证市场 URL 可访问
• 检查 .claude-plugin/marketplace.json 是否存在于指定路径
• 确保 JSON 语法有效：运行 claude plugin validate 或 /plugin validate。要检查 skill、agent 和 command 的 frontmatter，对每个插件目录运行命令
• 对于私有仓库，确认你有访问权限

市场验证错误 #

运行 claude plugin validate . 或 /plugin validate . 从市场目录检查问题。当指向市场目录时，验证器检查 marketplace.json 的 schema、重复插件名称、来源路径穿越以及版本与每个引用的 plugin.json 不匹配。

要验证单个插件的 plugin.json 及其 skill、agent、command 和 hook 文件，对插件目录本身运行命令，例如 claude plugin validate ./plugins/my-plugin。

常见错误：

警告（非阻塞）：

• Marketplace has no plugins defined：在 plugins 数组中至少添加一个插件
• No marketplace description provided：添加顶级 description 以帮助用户理解你的市场
• Plugin name "x" is not kebab-case：插件名包含大写字母、空格或特殊字符。重命名为仅包含小写字母、数字和连字符（如 my-plugin）。Claude Code 接受其他形式，但 Claude.ai 市场同步会拒绝它们

插件安装失败 #

症状：市场出现但插件安装失败

解决方案：

• 验证插件来源 URL 可访问
• 检查插件目录是否包含所需文件
• 对于 GitHub 来源，确保仓库是公开的或你有访问权限
• 手动通过克隆/下载测试插件来源

私有仓库认证失败 #

症状：从私有仓库安装插件时出现认证错误

解决方案：

手动安装和更新：

• 验证你已向 git 提供商认证（例如，对 GitHub 运行 gh auth status）
• 检查凭据助手是否正确配置：git config --global credential.helper
• 手动尝试克隆仓库以验证凭据是否正常工作

后台自动更新：

• 在环境中设置适当的令牌：echo $GITHUB_TOKEN
• 检查令牌是否具有必需的权限（对私有仓库至少为读取权限）
• 对于 GitHub，确保令牌具有 repo 范围（私有仓库）
• 对于 GitLab，确保令牌至少具有 read_repository 范围
• 验证令牌未过期

市场更新在离线环境中失败 #

症状：市场 git pull 失败，Claude Code 清除了现有缓存，导致插件不可用。

原因：默认情况下，当 git pull 失败时，Claude Code 会移除过时的克隆并尝试重新克隆。在离线或气隙环境中，重新克隆同样会失败，导致市场目录为空。

解决方案：设置 CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1，在拉取失败时保留现有缓存，而不是清除它：

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

设置此变量后，Claude Code 会在 git pull 失败时保留过时的市场克隆，并继续使用最后已知良好的状态。对于完全离线的部署（仓库永远无法访问），使用 CLAUDE_CODE_PLUGIN_SEED_DIR 在构建时预填充插件目录。

Git 操作超时 #

症状：插件安装或市场更新失败并显示超时错误，如 “Git clone timed out after 120s” 或 “Git pull timed out after 120s”。

原因：Claude Code 对所有 git 操作使用 120 秒超时，包括克隆插件仓库和拉取市场更新。大型仓库或慢速网络连接可能超过此限制。

解决方案：使用 CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS 环境变量增加超时时间。值以毫秒为单位：

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 minutes

插件相对路径在基于URL的市场中失效 #

症状：通过 URL（如 https://example.com/marketplace.json）添加市场，但使用相对路径来源（如 "./plugins/my-plugin"）的插件安装失败，显示 “path not found” 错误。

原因：基于 URL 的市场只下载 marketplace.json 文件本身。它们不会从服务器下载插件文件。市场条目中的相对路径引用的是远程服务器上的文件，而这些文件没有被下载。

解决方案：

• 使用外部来源：将插件条目改为使用 GitHub、npm 或 git URL 来源，而不是相对路径：

  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }

• 使用基于 Git 的市场：在 Git 仓库中托管市场，并使用 git URL 添加它。基于 Git 的市场会克隆整个仓库，使相对路径正确工作。

安装后文件找不到 #

症状：插件已安装，但引用文件失败，尤其是插件目录之外的文件。

原因：插件被复制到缓存目录而不是原地使用。引用插件目录之外文件（如 ../shared-utils）的路径将失效，因为这些文件未被复制。

解决方案：参见插件缓存与文件解析了解变通方法，包括符号链接和目录重组。

更多调试工具和常见问题参见调试与开发工具。

常见问题 #

strict: true 和 strict: false 有什么区别？怎么选择？ #

strict: true（默认）时，plugin.json 是组件定义的权威来源，市场条目可补充额外组件，两者合并加载。适合插件作者自行管理组件的场景。strict: false 时，市场条目是完整定义，插件仓库不需要 plugin.json（但若存在且声明了组件，会产生冲突导致加载失败）。适合市场运营者需要完全控制插件暴露哪些能力的场景，例如对第三方插件进行策展和重组。

如何防止用户添加未经审核的插件市场？ #

在托管设置中配置 strictKnownMarketplaces：设为 [] 完全禁止添加任何新市场，或填写允许的来源列表（支持 exact match、hostPattern 正则匹配和 pathPattern 正则匹配）。该设置在托管（managed）层，用户和项目配置无法覆盖。内部 Git 服务器建议使用正则匹配，避免逐一列出仓库 URL。若希望允许的市场自动可用，配合 extraKnownMarketplaces 使用。

容器里怎么让 Claude Code 启动时不重新克隆插件？ #

使用 CLAUDE_CODE_PLUGIN_SEED_DIR 在构建时预填充插件目录。构建镜像时运行一次 Claude Code 安装所需插件（可设 CLAUDE_CODE_PLUGIN_CACHE_DIR 直接写入目标路径），然后在容器运行时设置 CLAUDE_CODE_PLUGIN_SEED_DIR 指向该目录。种子目录只读且写入被禁止，启动时本地克隆被跳过，插件开箱即用。