> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建和分发 plugin marketplace

> 构建和托管 plugin marketplace，以在团队和社区中分发 Claude Code 扩展。

**plugin marketplace** 是一个目录，让你能够将 plugins 分发给他人。Marketplace 提供集中式发现、版本跟踪、自动更新以及对多种源类型（包括 git 存储库和本地路径）的支持。本指南展示了如何创建自己的 marketplace，与你的团队或社区共享 plugins。

想要从现有 marketplace 安装 plugins？请参阅[发现和安装预构建的 plugins](/docs/zh-CN/discover-plugins)。

<h2 id="overview">
  概述
</h2>

创建和分发 marketplace 涉及：

1. **创建 plugins**：使用 skills、agents、hooks、MCP servers 或 LSP servers 构建一个或多个 plugins。本指南假设你已经有要分发的 plugins；有关如何创建 plugins 的详细信息，请参阅[创建 plugins](/docs/zh-CN/plugins)。
2. **创建 marketplace 文件**：定义一个 `marketplace.json`，列出你的 plugins 及其位置。请参阅[创建 marketplace 文件](#create-the-marketplace-file)。
3. **托管 marketplace**：推送到 GitHub、GitLab 或其他 git 主机。请参阅[托管和分发 marketplaces](#host-and-distribute-marketplaces)。
4. **与用户共享**：用户使用 `/plugin marketplace add` 添加你的 marketplace 并安装单个 plugins。请参阅[发现和安装 plugins](/docs/zh-CN/discover-plugins)。

一旦你的 marketplace 上线，你可以通过推送更改到你的存储库来更新它。用户使用 `/plugin marketplace update` 刷新他们的本地副本。

<h2 id="walkthrough-create-a-local-marketplace">
  演练：创建本地 marketplace
</h2>

此示例创建一个包含一个 plugin 的 marketplace：一个用于代码审查的 `quality-review` skill。你将创建目录结构、添加 skill、创建 plugin manifest 和 marketplace 目录，然后安装并测试它。

<Steps>
  <Step title="创建目录结构">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="创建 skill">
    创建一个 `SKILL.md` 文件，定义 `quality-review` skill 的功能。

    ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}
    ---
    description: Review code for bugs, security, and performance
    ---

    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.
    ```
  </Step>

  <Step title="创建 plugin manifest">
    创建一个 `plugin.json` 文件，描述该 plugin。manifest 位于 `.claude-plugin/` 目录中。

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

    <Note>
      设置 `version` 意味着用户仅在你更改此字段时才会收到更新，因此在每次发布时都要提升版本号。如果你省略 `version` 并在 git 中托管此 marketplace，每次提交都会自动计为新版本。请参阅 [版本解析](#version-resolution-and-release-channels) 以选择正确的方法。
    </Note>
  </Step>

  <Step title="创建 marketplace 文件">
    创建列出你的 plugin 的 marketplace 目录。

    ```json my-marketplace/.claude-plugin/marketplace.json theme={null}
    {
      "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"
        }
      ]
    }
    ```
  </Step>

  <Step title="添加和安装">
    添加 marketplace 并安装 plugin。

    ```shell theme={null}
    /plugin marketplace add ./my-marketplace
    /plugin install quality-review-plugin@my-plugins
    ```
  </Step>

  <Step title="尝试一下">
    在编辑器中选择一些代码并运行你的新 skill。Plugin skills 使用 plugin 名称进行命名空间划分。

    ```shell theme={null}
    /quality-review-plugin:quality-review
    ```
  </Step>
</Steps>

要了解更多关于 plugins 可以做什么的信息，包括 hooks、agents、MCP servers 和 LSP servers，请参阅 [Plugins](/docs/zh-CN/plugins)。

<Note>
  **plugins 如何安装**：当用户安装 plugin 时，Claude Code 将 plugin 目录复制到缓存位置。这意味着 plugins 无法使用 `../shared-utils` 之类的路径引用其目录外的文件，因为这些文件不会被复制。

  如果你需要在 plugins 之间共享文件，请使用符号链接。有关详细信息，请参阅 [Plugin 缓存和文件解析](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution)。
</Note>

<h2 id="create-the-marketplace-file">
  创建 marketplace 文件
</h2>

在你的存储库根目录中创建 `.claude-plugin/marketplace.json`。此文件定义你的 marketplace 的名称、所有者信息以及包含其源的 plugins 列表。

每个 plugin 条目至少需要一个 `name` 和 `source`（告诉 Claude Code 从哪里获取它）。有关所有可用字段，请参阅下面的[完整架构](#marketplace-schema)。

```json theme={null}
{
  "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"
    }
  ]
}
```

<h2 id="marketplace-schema">
  Marketplace 架构
</h2>

<h3 id="required-fields">
  必需字段
</h3>

| 字段        | 类型     | 描述                                                                                                                                                                                                                                                                | 示例             |
| :-------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |
| `name`    | string | Marketplace 标识符（kebab-case，无空格）。这是面向公众的：用户在安装 plugins 时会看到它（例如，`/plugin install my-tool@your-marketplace`）。每个用户只能为每个名称注册一个 marketplace：添加第二个同名 marketplace 会替换第一个。要在一个 marketplace 名称下发布多个 plugins，请在[单个 `marketplace.json`](#create-the-marketplace-file) 中列出它们。 | `"acme-tools"` |
| `owner`   | object | Marketplace 维护者信息（[见下面的字段](#owner-fields)）                                                                                                                                                                                                                        |                |
| `plugins` | array  | 可用 plugins 列表                                                                                                                                                                                                                                                     | 见下文            |

<Note>
  **保留名称**：以下 marketplace 名称为 Anthropic 官方使用保留，第三方 marketplaces 无法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`claude-plugins-community`、`claude-community`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`knowledge-work-plugins`、`life-sciences`、`claude-for-legal`、`claude-for-financial-services`、`financial-services-plugins`、`first-party-plugins`、`healthcare`。冒充官方 marketplaces 的名称（如 `official-claude-plugins` 或 `anthropic-plugins-v2`）也被阻止。保留这些名称可防止第三方 marketplace 将自己呈现为 Anthropic 发布的来源。

  Claude Code 每次加载 marketplace 时都会重新检查保留名称，而不仅仅是在添加时。在该名称成为保留名称之前以其中一个名称注册的 marketplace 停止加载，并报告它是[从不受信任的来源注册的](/docs/zh-CN/errors#marketplace-is-registered-from-an-untrusted-source)。移除该 marketplace 并从官方 Anthropic 来源重新添加它。受新保留名称影响的第三方 marketplace 在你以不同名称重新添加它后立即再次加载。在 v2.1.205 之前，`first-party-plugins` 和 `healthcare` 不是保留的，已在保留名称下注册的 marketplace 继续加载。
</Note>

<h3 id="owner-fields">
  所有者字段
</h3>

| 字段      | 类型     | 必需 | 描述         |
| :------ | :----- | :- | :--------- |
| `name`  | string | 是  | 维护者或团队的名称  |
| `email` | string | 否  | 维护者的联系电子邮件 |

<h3 id="optional-fields">
  可选字段
</h3>

| 字段                                    | 类型     | 描述                                                                                                                                                                                                |
| :------------------------------------ | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `$schema`                             | string | 用于编辑器自动完成和验证的 JSON Schema URL。Claude Code 在加载时忽略此字段。                                                                                                                                              |
| `description`                         | string | 简短的 marketplace 描述                                                                                                                                                                                |
| `version`                             | string | Marketplace 清单版本                                                                                                                                                                                  |
| `metadata.pluginRoot`                 | string | 前置到相对 plugin 源路径的基目录（例如，`"./plugins"` 让你写 `"source": "formatter"` 而不是 `"source": "./plugins/formatter"`）                                                                                          |
| `allowCrossMarketplaceDependenciesOn` | array  | 此 marketplace 中的 plugins 可能依赖的其他 marketplaces。来自此处未列出的 marketplace 的依赖项在安装时被阻止。见[依赖来自另一个 marketplace 的 plugin](/docs/zh-CN/plugin-dependencies#depend-on-a-plugin-from-another-marketplace)。           |
| `renames`                             | object | {/* min-version: 2.1.193 */}从前一个 plugin `name` 到其当前名称的映射，或如果 plugin 被移除则映射到 `null`。当你重命名或移除 `plugins` 中的条目时，让现有用户自动迁移。见[重命名或移除 plugin](#rename-or-remove-a-plugin)。需要 Claude Code v2.1.193 或更高版本。 |

`description` 和 `version` 也可以在 `metadata` 下接受，以实现向后兼容性。

<h2 id="plugin-entries">
  Plugin 条目
</h2>

`plugins` 数组中的每个 plugin 条目描述一个 plugin 及其位置。你可以包含 [plugin manifest 架构](/docs/zh-CN/plugins-reference#plugin-manifest-schema)中的任何字段，如 `description`、`version`、`author`、`commands` 和 `hooks`，加上这些 marketplace 特定的字段：`source`、`category`、`tags`、`strict` 和 `relevance`。

<h3 id="required-fields-2">
  必需字段
</h3>

| 字段       | 类型             | 描述                                                                                         |
| :------- | :------------- | :----------------------------------------------------------------------------------------- |
| `name`   | string         | Plugin 标识符（kebab-case，无空格）。这是面向公众的：用户在安装时会看到它（例如，`/plugin install my-plugin@marketplace`）。 |
| `source` | string\|object | 从哪里获取 plugin（见下面的 [Plugin 源](#plugin-sources)）                                             |

<h3 id="optional-plugin-fields">
  可选 plugin 字段
</h3>

**标准元数据字段：**

| 字段               | 类型      | 描述                                                                                                                                                                                                            |
| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `displayName`    | string  | {/* min-version: 2.1.143 */}在 UI 界面中显示的人类可读名称。当省略时回退到 `name`。可以包含空格和任何大小写。不用于命名空间或查找。需要 Claude Code v2.1.143 或更高版本。                                                                                           |
| `description`    | string  | 简短的 plugin 描述                                                                                                                                                                                                 |
| `version`        | string  | Plugin 版本。如果设置（在此处或在 `plugin.json` 中），plugin 将固定到此字符串，用户仅在其更改时才会收到更新。省略以回退到 git commit SHA。见 [版本解析](#version-resolution-and-release-channels)。                                                                |
| `author`         | object  | Plugin 作者信息（`name` 必需，`email` 可选）                                                                                                                                                                             |
| `homepage`       | string  | Plugin 主页或文档 URL                                                                                                                                                                                              |
| `repository`     | string  | 源代码存储库 URL                                                                                                                                                                                                    |
| `license`        | string  | SPDX 许可证标识符（例如，MIT、Apache-2.0）                                                                                                                                                                                |
| `keywords`       | array   | 用于 plugin 发现和分类的标签                                                                                                                                                                                            |
| `category`       | string  | Plugin 类别以供组织                                                                                                                                                                                                 |
| `tags`           | array   | 用于可搜索性的标签                                                                                                                                                                                                     |
| `strict`         | boolean | 控制 `plugin.json` 是否是组件定义的权威（默认：true）。见下面的 [Strict 模式](#strict-mode)。                                                                                                                                          |
| `relevance`      | object  | {/* min-version: 2.1.152 */}告诉 Claude Code 何时向用户建议此 plugin 的信号。仅对管理员在托管设置中允许列表的 marketplace 生效。见 [为你的组织推荐 plugin](/docs/zh-CN/plugin-relevance)。需要 Claude Code v2.1.152 或更高版本。                                     |
| `defaultEnabled` | boolean | {/* min-version: 2.1.154 */}plugin 安装后是否启用（默认：true）。设置为 `false` 以安装禁用的 plugin，直到用户选择启用。优先于 plugin 的 `plugin.json` 中的同一字段。见 [默认启用](/docs/zh-CN/plugins-reference#default-enablement)。需要 Claude Code v2.1.154 或更高版本。 |

**组件配置字段：**

| 字段           | 类型             | 描述                                    |
| :----------- | :------------- | :------------------------------------ |
| `skills`     | string\|array  | 包含 `<name>/SKILL.md` 的 skill 目录的自定义路径 |
| `commands`   | string\|array  | 平面 `.md` skill 文件或目录的自定义路径            |
| `agents`     | string\|array  | agent 文件的自定义路径                        |
| `hooks`      | string\|object | 自定义 hooks 配置或 hooks 文件的路径             |
| `mcpServers` | string\|object | MCP server 配置或 MCP 配置的路径              |
| `lspServers` | string\|object | LSP server 配置或 LSP 配置的路径              |

<h2 id="plugin-sources">
  Plugin 源
</h2>

Plugin 源告诉 Claude Code 在你的 marketplace 中列出的每个单独 plugin 从哪里获取。这些在 `marketplace.json` 中每个 plugin 条目的 `source` 字段中设置。

一旦 Claude Code 克隆或下载 plugin 到本地机器，它就会将 plugin 复制到本地版本化 plugin 缓存中，位置为 `~/.claude/plugins/cache`。

| 源            | 类型                           | 字段                               | 注释                                                                                 |
| ------------ | ---------------------------- | -------------------------------- | ---------------------------------------------------------------------------------- |
| 相对路径         | `string`（例如 `"./my-plugin"`） | 无                                | marketplace repo 中的本地目录。必须以 `./` 开头。相对于 marketplace 根目录解析，而不是 `.claude-plugin/` 目录 |
| `github`     | object                       | `repo`、`ref?`、`sha?`             |                                                                                    |
| `url`        | object                       | `url`、`ref?`、`sha?`              | Git URL 源                                                                          |
| `git-subdir` | object                       | `url`、`path`、`ref?`、`sha?`       | git repo 中的子目录。稀疏克隆以最小化大型 monorepos 的带宽                                            |
| `npm`        | object                       | `package`、`version?`、`registry?` | 通过 `npm install` 安装                                                                |

<Note>
  **Marketplace 源与 plugin 源**：这些是控制不同事物的不同概念。

  * **Marketplace 源**：从哪里获取 `marketplace.json` 目录本身。在用户运行 `/plugin marketplace add` 或在 `extraKnownMarketplaces` 设置中设置。支持 `ref`（分支/标签）但不支持 `sha`。
  * **Plugin 源**：从哪里获取 marketplace 中列出的单个 plugin。在 `marketplace.json` 内每个 plugin 条目的 `source` 字段中设置。支持 `ref`（分支/标签）和 `sha`（精确提交）。

  例如，托管在 `acme-corp/plugin-catalog` 的 marketplace（marketplace 源）可以列出从 `acme-corp/code-formatter` 获取的 plugin（plugin 源）。marketplace 源和 plugin 源指向不同的存储库，并独立固定。
</Note>

基于 git 的源类型如下所示为 `github`、`url` 和 `git-subdir`。当在其中任何一个上同时设置 `ref` 和 `sha` 时，`sha` 是有效的固定。Claude Code 直接获取并检出固定的提交。在大多数 git 主机上，包括 GitHub、GitLab 和 Bitbucket，这意味着即使上游的 `ref` 命名的分支或标签已被删除，只要提交仍然可从存储库到达，安装也会成功。某些服务器（如 AWS CodeCommit）不支持通过 SHA 获取提交。在这些服务器上，`ref` 必须仍然存在，固定的提交必须可从其到达。

<h3 id="relative-paths">
  相对路径
</h3>

对于同一存储库中的 plugins，使用以 `./` 开头的路径：

```json theme={null}
{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}
```

路径相对于 marketplace 根目录解析，即包含 `.claude-plugin/` 的目录。在上面的示例中，`./plugins/my-plugin` 指向 `<repo>/plugins/my-plugin`，即使 `marketplace.json` 位于 `<repo>/.claude-plugin/marketplace.json`。不要使用 `../` 来引用 marketplace 根目录外的路径。

<Note>
  相对路径仅在用户通过 git 源或本地目录添加你的 marketplace 时有效。如果用户通过直接 URL 添加你的 marketplace 到 `marketplace.json` 文件，相对路径将无法解析，因为只有该文件被下载。对于基于 URL 的分发，请改用 GitHub、npm 或 git URL 源。有关详细信息，请参阅[故障排除](#plugins-with-relative-paths-fail-in-url-based-marketplaces)。
</Note>

<h3 id="github-repositories">
  GitHub 存储库
</h3>

```json theme={null}
{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}
```

你可以固定到特定的分支、标签或提交：

```json theme={null}
{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}
```

| 字段     | 类型     | 描述                               |
| :----- | :----- | :------------------------------- |
| `repo` | string | 必需。`owner/repo` 格式的 GitHub 存储库   |
| `ref`  | string | 可选。Git 分支或标签（默认为存储库默认分支）         |
| `sha`  | string | 可选。完整的 40 字符 git 提交 SHA 以固定到精确版本 |

<h3 id="git-repositories">
  Git 存储库
</h3>

```json theme={null}
{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}
```

你可以固定到特定的分支、标签或提交：

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

| 字段    | 类型     | 描述                                                                                                   |
| :---- | :----- | :--------------------------------------------------------------------------------------------------- |
| `url` | string | 必需。完整的 git 存储库 URL（`https://` 或 `git@`）。`.git` 后缀是可选的，所以 Azure DevOps 和 AWS CodeCommit URL 不带后缀也可以工作 |
| `ref` | string | 可选。Git 分支或标签（默认为存储库默认分支）                                                                             |
| `sha` | string | 可选。完整的 40 字符 git 提交 SHA 以固定到精确版本                                                                     |

<h3 id="git-subdirectories">
  Git 子目录
</h3>

使用 `git-subdir` 指向位于 git 存储库子目录中的 plugin。Claude Code 使用稀疏的部分克隆来仅获取子目录，最小化大型 monorepos 的带宽。

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

你可以固定到特定的分支、标签或提交：

```json theme={null}
{
  "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`）。

| 字段     | 类型     | 描述                                                    |
| :----- | :----- | :---------------------------------------------------- |
| `url`  | string | 必需。Git 存储库 URL、GitHub `owner/repo` 简写或 SSH URL        |
| `path` | string | 必需。repo 中包含 plugin 的子目录路径（例如，`"tools/claude-plugin"`） |
| `ref`  | string | 可选。Git 分支或标签（默认为存储库默认分支）                              |
| `sha`  | string | 可选。完整的 40 字符 git 提交 SHA 以固定到精确版本                      |

<h3 id="npm-packages">
  npm 包
</h3>

作为 npm 包分发的 Plugins 使用 `npm install` 安装。这适用于公共 npm registry 上的任何包或你的团队托管的私有 registry。

```json theme={null}
{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}
```

要固定到特定版本，请添加 `version` 字段：

```json theme={null}
{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}
```

要从私有或内部 registry 安装，请添加 `registry` 字段：

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

| 字段         | 类型     | 描述                                                        |
| :--------- | :----- | :-------------------------------------------------------- |
| `package`  | string | 必需。包名称或作用域包（例如，`@org/plugin`）                             |
| `version`  | string | 可选。版本或版本范围（例如，`2.1.0`、`^2.0.0`、`~1.5.0`）                  |
| `registry` | string | 可选。自定义 npm registry URL。默认为系统 npm registry（通常为 npmjs.org） |

<h3 id="advanced-plugin-entries">
  高级 plugin 条目
</h3>

此示例显示了使用许多可选字段的 plugin 条目，包括命令、agents、hooks 和 MCP servers 的自定义路径：

```json theme={null}
{
  "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`**：你可以指定多个目录或单个文件。路径相对于 plugin 根目录。
* **`${CLAUDE_PLUGIN_ROOT}`**：在 hooks 和 MCP server 配置中使用此变量来引用 plugin 安装目录中的文件。这是必要的，因为 plugins 在安装时被复制到缓存位置。
  * 查看[替换表](/docs/zh-CN/plugins-reference#environment-variables)了解每个服务器类型在哪些配置字段中替换它
  * 对于应该在 plugin 更新后保留的依赖项或状态，请改用 [`${CLAUDE_PLUGIN_DATA}`](/docs/zh-CN/plugins-reference#persistent-data-directory)
* **`strict: false`**：由于这设置为 false，plugin 不需要自己的 `plugin.json`。marketplace 条目定义了一切。见下面的 [Strict 模式](#strict-mode)。

默认情况下，plugin 的 skills 从其 `source` 下的 `skills/` 目录加载。`skills` 字段中列出的路径添加到该扫描中：

```json theme={null}
"skills": ["./skills/", "./extra-skills/"]
```

当多个 plugin 条目在 marketplace 根目录（`source: "./"`）共享一个 `skills/` 文件夹时，改为列出特定子目录，以便每个条目仅加载自己的 skills：

```json theme={null}
"source": "./",
"skills": ["./skills/code-review", "./skills/docs"]
```

使用 marketplace 根源，列出的路径是该条目的完整集合，共享 `skills/` 文件夹中的其他目录不会加载。列出 `./skills/` 本身或 plugin 根目录会保持完整扫描。如果列出的路径都不存在，则改为运行默认扫描。

<h3 id="strict-mode">
  Strict 模式
</h3>

`strict` 字段控制 `plugin.json` 是否是组件定义（skills、agents、hooks、MCP servers、输出样式）的权威。

| 值          | 行为                                                                      |
| :--------- | :---------------------------------------------------------------------- |
| `true`（默认） | `plugin.json` 是权威。marketplace 条目可以用额外的组件补充它，两个源都被合并。                    |
| `false`    | marketplace 条目是完整的定义。如果 plugin 也有声明组件的 `plugin.json`，那就是冲突，plugin 无法加载。 |

**何时使用每种模式：**

* **`strict: true`**：plugin 有自己的 `plugin.json` 并管理自己的组件。marketplace 条目可以在顶部添加额外的 skills 或 hooks。这是默认值，适用于大多数 plugins。
* **`strict: false`**：marketplace 操作员想要完全控制。plugin repo 提供原始文件，marketplace 条目定义这些文件中的哪些被公开为 skills、agents、hooks 等。当 marketplace 以不同于 plugin 作者意图的方式重组或策划 plugin 的组件时很有用。

<h2 id="host-and-distribute-marketplaces">
  托管和分发 marketplaces
</h2>

<h3 id="host-on-github-recommended">
  在 GitHub 上托管（推荐）
</h3>

GitHub 是托管和分发 marketplace 的推荐方式：

1. **创建存储库**：为你的 marketplace 设置一个新存储库
2. **添加 marketplace 文件**：使用你的 plugin 定义创建 `.claude-plugin/marketplace.json`
3. **与团队共享**：用户使用 `/plugin marketplace add owner/repo` 添加你的 marketplace

**优点**：内置版本控制、问题跟踪和团队协作功能。

<h3 id="host-on-other-git-services">
  在其他 git 服务上托管
</h3>

任何 git 托管服务都可以工作，例如 GitLab、Bitbucket 和自托管服务器。用户使用完整的存储库 URL 添加：

```shell theme={null}
/plugin marketplace add https://gitlab.com/company/plugins.git
```

<h3 id="private-repositories">
  私有存储库
</h3>

Claude Code 支持从私有存储库安装 plugins。对于手动安装和更新，Claude Code 使用你现有的 git 凭证助手，所以通过 `gh auth login`、macOS Keychain 或 `git-credential-store` 的 HTTPS 访问工作方式与你的终端中相同。SSH 访问工作，只要主机已经在你的 `known_hosts` 文件中，并且密钥已加载到 `ssh-agent` 中，因为 Claude Code 会抑制主机指纹和密钥密码的交互式 SSH 提示。GitHub `owner/repo` 简写源默认通过 SSH 克隆；设置 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-CN/env-vars#variables) 以改为通过 HTTPS 克隆它们。

后台自动更新的工作方式不同。默认情况下，后台刷新会为其 `git pull` 禁用 git 凭证助手，所以即使配置了助手，pull 也无法对 HTTPS 上的私有存储库进行身份验证。SSH 远程不受影响：加载到 `ssh-agent` 中的密钥以与手动操作相同的方式对后台 pulls 进行身份验证。当后台 pull 失败时，Claude Code 会回退到从头重新克隆 marketplace。重新克隆确实使用你存储的 git 凭证，但它可能在大型存储库上[超时](#git-operations-time-out)，所以私有 marketplace 自动更新可能会间歇性失败。

两个设置使私有 marketplaces 的行为可预测：

* 设置 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在后台 pull 失败时保留现有克隆，而不是删除并重新克隆。你的 plugins 继续从最后同步的状态工作，使用 `/plugin marketplace update` 的手动更新仍然使用你的凭证进行 pull。
* 配置 git 凭证助手，例如使用 `gh auth setup-git` 用于 GitHub，以便重新克隆回退可以在不提示的情况下进行身份验证。

在你的环境中设置提供商令牌（如 `GITHUB_TOKEN`）本身不会启用后台身份验证。令牌仅通过配置的凭证助手（例如 `gh` CLI 的助手，它读取 `GH_TOKEN` 和 `GITHUB_TOKEN`）生效。

要使后台 pull 本身通过 HTTPS 进行身份验证，请配置全局 git URL 重写。重写在远程 URL 中嵌入令牌，所以即使后台 pull 禁用凭证助手，它也会生效，成功的 pull 会跳过重新克隆回退。以下示例重写 marketplace 存储库的 URL 以包含访问令牌：

```bash theme={null}
git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"
```

将重写范围限制在 marketplace 存储库或组织路径。仅以主机为基础的重写适用于机器上对该主机的每个 fetch 和 push，并覆盖你的正常凭证，包括对你自己的存储库的 pushes。

每个提供商在重写的 URL 中期望不同的用户名，相同的路径范围适用于每个提供商。对于自托管服务器，请将主机名替换为你的服务器的主机名：

| 提供商       | 重写的 URL 形式                                                        |
| :-------- | :---------------------------------------------------------------- |
| GitHub    | `https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins`  |
| GitLab    | `https://oauth2:YOUR_TOKEN@gitlab.com/acme-corp/plugins`          |
| Bitbucket | `https://x-token-auth:YOUR_TOKEN@bitbucket.org/acme-corp/plugins` |

重写以纯文本形式在你的 gitconfig 中存储令牌，所以使用对 marketplace 存储库具有只读访问权限的令牌。

<Note>
  在 CI/CD 环境中，在从私有存储库安装 plugins 之前配置 git 凭证助手。在 GitHub Actions 上，导出对 marketplace 存储库具有读取访问权限的令牌作为 `GH_TOKEN`，然后运行 `gh auth setup-git`。默认工作流令牌只能访问工作流自己的存储库，所以另一个存储库中的私有 marketplace 需要个人访问令牌或应用令牌。在管道中配置的全局 URL 重写也直接对后台 pull 进行身份验证。
</Note>

<h3 id="test-locally-before-distribution">
  在分发前本地测试
</h3>

在共享前本地测试你的 marketplace：

```shell theme={null}
/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins
```

有关完整的添加命令范围（GitHub、Git URL、本地路径、远程 URL），请参阅[添加 marketplaces](/docs/zh-CN/discover-plugins#add-marketplaces)。

<h3 id="require-marketplaces-for-your-team">
  为你的团队要求 marketplaces
</h3>

你可以配置你的存储库，以便当团队成员信任项目文件夹时，他们会自动被提示安装你的 marketplace。将你的 marketplace 添加到 `.claude/settings.json`：

```json theme={null}
{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}
```

你也可以指定默认应启用哪些 plugins：

```json theme={null}
{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}
```

有关完整的配置选项，请参阅 [Plugin 设置](/docs/zh-CN/settings#plugin-settings)。

<Note>
  如果你使用带有相对路径的本地 `directory` 或 `file` 源，路径将相对于你的存储库的主检出解析。当你从 git worktree 运行 Claude Code 时，路径仍然指向主检出，所以所有 worktrees 共享相同的 marketplace 位置。Marketplace 状态存储一次每个用户在 `~/.claude/plugins/known_marketplaces.json` 中，而不是每个项目。
</Note>

<h3 id="pre-populate-plugins-for-containers">
  为容器预填充 plugins
</h3>

对于容器镜像和 CI 环境，你可以在构建时预填充 plugins 目录，以便 Claude Code 启动时已经有 marketplaces 和 plugins 可用，无需在运行时克隆任何内容。设置 `CLAUDE_CODE_PLUGIN_SEED_DIR` 环境变量以指向此目录。

要分层多个种子目录，请在 Unix 上用 `:` 分隔路径，或在 Windows 上用 `;` 分隔。Claude Code 按顺序搜索每个目录，第一个包含给定 marketplace 或 plugin 缓存的种子获胜。

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

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

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

要跳过复制步骤，请在构建期间将 `CLAUDE_CODE_PLUGIN_CACHE_DIR` 设置为你的目标种子路径，以便 plugins 直接安装到那里：

```bash theme={null}
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` 中找到的 marketplaces 注册到主配置中，并使用在 `cache/` 下找到的 plugin 缓存，而无需重新克隆。这在交互模式和使用 `-p` 标志的非交互模式中都有效。

行为详情：

* **只读**：种子目录永远不会被写入。由于 git pull 会在只读文件系统上失败，种子 marketplaces 的自动更新被禁用。
* **种子条目优先**：在每次启动时，种子中声明的 marketplaces 会覆盖用户配置中的任何匹配条目。要选择退出种子 plugin，请使用 `/plugin disable` 而不是删除 marketplace。
* **路径解析**：Claude Code 通过在运行时探测 `$CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/` 来定位 marketplace 内容，而不是信任存储在种子 JSON 内的路径。这意味着即使在与构建时不同的路径上挂载，种子也能正确工作。
* **变更被阻止**：针对种子管理的 marketplace 运行 `/plugin marketplace remove` 或 `/plugin marketplace update` 会失败，并提示你要求管理员更新种子镜像。
* **与设置组合**：如果 `extraKnownMarketplaces` 或 `enabledPlugins` 声明的 marketplace 已经存在于种子中，Claude Code 使用种子副本而不是克隆。

<h3 id="managed-marketplace-restrictions">
  托管 marketplace 限制
</h3>

对于需要严格控制 plugin 源的组织，管理员可以使用托管设置中的 [`strictKnownMarketplaces`](/docs/zh-CN/settings#strictknownmarketplaces) 设置限制用户允许添加哪些 plugin marketplaces。要同时拒绝为单次运行 sideload plugins、agents 和 MCP servers 的 CLI 标志，请将其与 [`disableSideloadFlags`](/docs/zh-CN/settings#available-settings) 配对。要允许列表哪些 marketplaces 的 plugins 可以作为上下文安装建议出现，请设置 [`pluginSuggestionMarketplaces`](/docs/zh-CN/settings#available-settings)。

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

| 值        | 行为                            |
| -------- | ----------------------------- |
| 未定义（默认）  | 无限制。用户可以添加任何 marketplace      |
| 空数组 `[]` | 完全锁定。用户无法添加任何新 marketplaces   |
| 源列表      | 用户只能添加与允许列表完全匹配的 marketplaces |

<h4 id="common-configurations">
  常见配置
</h4>

禁用所有 marketplace 添加：

```json theme={null}
{
  "strictKnownMarketplaces": []
}
```

仅允许特定 marketplaces：

```json theme={null}
{
  "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 服务器的所有 marketplaces。这是 [GitHub Enterprise Server](/docs/zh-CN/github-enterprise-server#plugin-marketplaces-on-ghes) 或自托管 GitLab 实例的推荐方法：

```json theme={null}
{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}
```

使用路径上的正则表达式模式匹配允许来自特定目录的基于文件系统的 marketplaces：

```json theme={null}
{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}
```

使用 `".*"` 作为 `pathPattern` 来允许任何文件系统路径，同时仍然使用 `hostPattern` 控制网络源。

<Note>
  `strictKnownMarketplaces` 限制用户可以添加的内容，但不会自行注册 marketplaces。要使允许的 marketplaces 自动可用而无需用户运行 `/plugin marketplace add`，请在同一 `managed-settings.json` 中将其与 [`extraKnownMarketplaces`](/docs/zh-CN/settings#extraknownmarketplaces) 配对。见[同时使用两者](/docs/zh-CN/settings#strictknownmarketplaces)。
</Note>

<h4 id="how-restrictions-work">
  限制如何工作
</h4>

限制在任何网络或文件系统操作之前进行检查。检查在 marketplace 添加以及 plugin 安装、更新、刷新和自动更新时运行。如果 marketplace 在配置策略之前被添加，其源不再与允许列表匹配，Claude Code 会拒绝从中安装或更新 plugins。相同的强制执行也适用于 `blockedMarketplaces`。

允许列表对大多数源类型使用精确匹配。要允许 marketplace，所有指定的字段必须完全匹配：

* 对于 GitHub 源：`repo` 是必需的，如果在允许列表中指定，`ref` 或 `path` 也必须匹配
* 对于 URL 源：完整 URL 必须完全匹配
* 对于 `hostPattern` 源：marketplace 主机与正则表达式模式匹配
* 对于 `pathPattern` 源：marketplace 的文件系统路径与正则表达式模式匹配

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

因为 `strictKnownMarketplaces` 在[托管设置](/docs/zh-CN/settings#settings-files)中设置，个别用户和项目配置无法覆盖这些限制。

有关完整的配置详细信息，包括所有支持的源类型和与 `extraKnownMarketplaces` 的比较，请参阅 [strictKnownMarketplaces 参考](/docs/zh-CN/settings#strictknownmarketplaces)。

<h3 id="version-resolution-and-release-channels">
  版本解析和发布渠道
</h3>

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

Claude Code 从以下第一个设置的内容解析 plugin 的版本：

1. plugin 的 `plugin.json` 中的 `version`
2. plugin 的 marketplace 条目中的 `version`
3. plugin 源的 git 提交 SHA

对于 git 源类型 `github`、`url`、`git-subdir` 和 git 托管 marketplace 内的相对路径，你可以完全省略 `version`，每个新提交都被视为新版本。这是内部或积极开发的 plugins 的最简单设置。

<Warning>
  设置 `version` 会固定 plugin。如果 `plugin.json` 声明 `"version": "1.0.0"`，推送新提交而不改变该字符串对现有用户没有任何作用，因为 Claude Code 看到相同的版本并保留缓存副本。在每个发布时提升该字段，或省略它以使用提交 SHA。

  避免在 `plugin.json` 和 marketplace 条目中都设置 `version`。Claude Code 总是无声地使用 `plugin.json` 值，所以陈旧的 manifest 版本可能会掩盖你在 `marketplace.json` 中设置的版本。
</Warning>

<h4 id="set-up-release-channels">
  设置发布渠道
</h4>

要为你的 plugins 支持"稳定"和"最新"发布渠道，你可以设置两个指向同一 repo 的不同 refs 或 SHAs 的 marketplaces。然后，你可以通过[托管设置](/docs/zh-CN/settings#settings-files)将两个 marketplaces 分配给不同的用户组。

<Warning>
  每个渠道必须解析为不同的版本。如果你使用显式版本，`plugin.json` 必须在每个固定的 ref 处声明不同的 `version`。如果你省略 `version`，不同的提交 SHA 已经区分了渠道。如果两个 refs 解析为相同的版本字符串，Claude Code 会将它们视为相同并跳过更新。
</Warning>

<h5 id="example">
  示例
</h5>

```json theme={null}
{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}
```

```json theme={null}
{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}
```

<h5 id="assign-channels-to-user-groups">
  将渠道分配给用户组
</h5>

通过托管设置将每个 marketplace 分配给适当的用户组。例如，稳定组接收：

```json theme={null}
{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}
```

早期访问组改为接收 `latest-tools`：

```json theme={null}
{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}
```

<h4 id="pin-dependency-versions">
  固定依赖版本
</h4>

Plugin 可以将其依赖约束到 semver 范围，以便对依赖的更新不会破坏依赖的 plugin。有关 `{plugin-name}--v{version}` git 标签约定、范围语法以及如何组合对同一依赖的多个约束，请参阅[约束 plugin 依赖版本](/docs/zh-CN/plugin-dependencies)。

<h3 id="rename-or-remove-a-plugin">
  重命名或删除 plugin
</h3>

Plugin 的 `name` 是其稳定标识符。用户在 `enabledPlugins`、`pluginConfigs` 和 `/plugin install` 命令中引用它，所以改变它会破坏每个现有的安装。要改变 UI 中显示的标签而不破坏安装，请设置 [`displayName`](#optional-plugin-fields) 并保持 `name` 不变。

如果你必须改变 plugin 的 `name`，或者你从 `plugins` 数组中删除 plugin，请添加顶级 `renames` 条目，以便现有用户迁移而不是看到 `plugin-not-found` 错误。自动迁移需要 Claude Code v2.1.193 或更高版本。将每个前名称映射到其当前名称，或映射到 `null` 如果 plugin 不再存在。以下示例将 `formatter` 重命名为 `code-formatter` 并记录 `legacy-linter` 已被删除：

```json theme={null}
{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}
```

当用户启动 Claude Code 时旧名称仍在其设置中，Claude Code 遵循 `renames` 映射：

* 如果条目指向新名称，Claude Code 在其新名称下加载 plugin 并显示一行通知，例如 `在"acme-tools" marketplace 中重命名为"code-formatter"`。然后它在用户、项目和本地设置范围中为 `enabledPlugins` 和 `pluginConfigs` 都将旧键重写为新键，所以通知只出现一次。
* 对于 `null` 条目，Claude Code 删除旧键，通知报告 plugin 已从 marketplace 中删除。
* 如果重命名的 plugin 使用远程源，例如 `github` 或 `npm`，Claude Code 在重命名后报告 `plugin-cache-miss`，用户必须运行 `/plugin install` 一次以在新名称下获取它。

将 `renames` 视为仅追加历史：即使在你期望每个用户都已迁移后，也要保持旧条目就位。Claude Code 遵循链，所以如果你稍后将 `code-formatter` 重命名为 `formatter-pro`，请添加第二个条目而不是编辑第一个。仍然启用原始 `formatter` 的用户然后通过两个条目解析到 `formatter-pro`。

在编辑映射后运行 `claude plugin validate .`；它拒绝任何链形成循环或不终止于 `null` 或 `plugins` 中列出的名称的条目。

<Note>
  托管和策略设置对 Claude Code 是只读的，所以在那里启用的 plugins 无法自动重写。重命名的 plugin 仍然在每个会话中加载，但重命名通知会重复出现，直到管理员更新托管设置文件中的 `enabledPlugins` 以使用新名称。相同的情况适用于通过其他只读源（例如 `--add-dir`）启用的 plugins。
</Note>

早期版本的 Claude Code 忽略 `renames` 字段并为旧名称报告 `plugin-not-found`。

<h2 id="validation-and-testing">
  验证和测试
</h2>

在共享前测试你的 marketplace。

验证你的 marketplace JSON 语法：

```bash theme={null}
claude plugin validate .
```

或从 Claude Code 内：

```shell theme={null}
/plugin validate .
```

添加 marketplace 进行测试：

```shell theme={null}
/plugin marketplace add ./path/to/marketplace
```

安装测试 plugin 以验证一切正常：

```shell theme={null}
/plugin install test-plugin@marketplace-name
```

有关完整的 plugin 测试工作流，请参阅[本地测试你的 plugins](/docs/zh-CN/plugins#test-your-plugins-locally)。有关技术故障排除，请参阅 [Plugins 参考](/docs/zh-CN/plugins-reference)。

<h2 id="manage-marketplaces-from-the-cli">
  从 CLI 管理 marketplaces
</h2>

Claude Code 提供非交互式 `claude plugin marketplace` 子命令用于脚本编写和自动化。这些等同于交互式会话中可用的 `/plugin marketplace` 命令。

<h3 id="plugin-marketplace-add">
  Plugin marketplace add
</h3>

从 GitHub 存储库、git URL、远程 URL 或本地路径添加 marketplace。

```bash theme={null}
claude plugin marketplace add <source> [options]
```

**参数：**

* `<source>`：GitHub `owner/repo` 简写、git URL、指向 `marketplace.json` 文件的远程 URL 或本地目录路径。要固定到分支或标签，请将 `@ref` 附加到 GitHub 简写或 `#ref` 附加到 git URL

URL 必须包含其方案。从 Claude Code v2.1.196 开始，没有方案的主机（如 `gitlab.example.com/team/plugins`）被拒绝为无效的 `owner/repo` 简写，错误会告诉你添加 `https://` 或为本地路径使用 `./`。早期版本会将其误读为 GitHub 存储库路径，并在克隆时失败，出现 GitHub 未找到错误。

**选项：**

| 选项                    | 描述                                                                                                                 | 默认值    |
| :-------------------- | :----------------------------------------------------------------------------------------------------------------- | :----- |
| `--scope <scope>`     | 声明 marketplace 的位置：`user`、`project` 或 `local`。见 [Plugin 安装范围](/docs/zh-CN/plugins-reference#plugin-installation-scopes) | `user` |
| `--sparse <paths...>` | 通过 git sparse-checkout 限制检出到特定目录。对 monorepos 有用                                                                    |        |

从 GitHub 使用 `owner/repo` 简写添加 marketplace：

```bash theme={null}
claude plugin marketplace add acme-corp/claude-plugins
```

使用 `@ref` 固定到特定分支或标签：

```bash theme={null}
claude plugin marketplace add acme-corp/claude-plugins@v2.0
```

从非 GitHub 主机上的 git URL 添加：

```bash theme={null}
claude plugin marketplace add https://gitlab.example.com/team/plugins.git
```

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

```bash theme={null}
claude plugin marketplace add https://example.com/marketplace.json
```

从本地目录添加以进行测试：

```bash theme={null}
claude plugin marketplace add ./my-marketplace
```

在项目范围声明 marketplace，以便通过 `.claude/settings.json` 与你的团队共享：

```bash theme={null}
claude plugin marketplace add acme-corp/claude-plugins --scope project
```

对于 monorepo，限制检出到包含 plugin 内容的目录：

```bash theme={null}
claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins
```

<h3 id="plugin-marketplace-list">
  Plugin marketplace list
</h3>

列出所有配置的 marketplaces。

```bash theme={null}
claude plugin marketplace list [options]
```

**选项：**

| 选项       | 描述       |
| :------- | :------- |
| `--json` | 输出为 JSON |

使用 `--json`，每个条目包括 `name`、`source` 和源特定字段：GitHub 源的 `repo`、git 和 URL 源的 `url`，以及本地源的 `path`。当 marketplace 使用固定分支或标签添加时，GitHub 和 git 源也包括 `ref` 字段。

<h3 id="plugin-marketplace-remove">
  Plugin marketplace remove
</h3>

删除配置的 marketplace。别名 `rm` 也被接受。

```bash theme={null}
claude plugin marketplace remove <name> [options]
```

**参数：**

* `<name>`：marketplace 名称要删除，如 `claude plugin marketplace list` 所示。这是来自 `marketplace.json` 的 `name`，而不是你传递给 `add` 的源

**选项：**

| 选项                | 描述                                                                                                                                                                                                | 默认值    |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----- |
| `--scope <scope>` | 限制删除到单个设置范围：`user`、`project` 或 `local`。见 [Plugin 安装范围](/docs/zh-CN/plugins-reference#plugin-installation-scopes)。省略时，声明从每个可编辑的范围中删除。给定时，仅删除该范围的声明；当 marketplace 仍在另一个范围中声明时，共享状态、缓存和已安装的 plugin 数据将被保留 | （所有范围） |

<Warning>
  从其最后剩余的范围中删除 marketplace 也会卸载你从它安装的任何 plugins。要刷新 marketplace 而不丢失已安装的 plugins，请改用 `claude plugin marketplace update`。
</Warning>

<h3 id="plugin-marketplace-update">
  Plugin marketplace update
</h3>

从其源刷新 marketplaces 以检索新 plugins 和版本更改。使用分支或标签 `ref` 添加的 marketplace 会更新到该 ref 的最新提交，而不是存储库的默认分支。

```bash theme={null}
claude plugin marketplace update [name]
```

**参数：**

* `[name]`：marketplace 名称要更新，如 `claude plugin marketplace list` 所示。如果省略，更新所有 marketplaces

`remove` 和 `update` 在针对种子管理的 marketplace 运行时都会失败，这是只读的。更新所有 marketplaces 时，种子管理的条目被跳过，其他 marketplaces 仍然更新。要更改种子提供的 plugins，请要求你的管理员更新种子镜像。见 [为容器预填充 plugins](#pre-populate-plugins-for-containers)。

<h2 id="troubleshooting">
  故障排除
</h2>

<h3 id="marketplace-not-loading">
  Marketplace 未加载
</h3>

**症状**：无法添加 marketplace 或从中看到 plugins

**解决方案**：

* 验证 marketplace URL 是否可访问
* 检查 `.claude-plugin/marketplace.json` 是否存在于指定路径
* 使用 `claude plugin validate` 或 `/plugin validate` 确保 JSON 语法有效。要检查 skill、agent 和 command frontmatter，请针对每个 plugin 目录运行该命令
* 对于私有存储库，确认你有访问权限

<h3 id="marketplace-validation-errors">
  Marketplace 验证错误
</h3>

从你的 marketplace 目录运行 `claude plugin validate .` 或 `/plugin validate .` 来检查问题。当指向 marketplace 目录时，验证器检查 `marketplace.json` 是否存在 schema 错误、重复的 plugin 名称和源路径遍历。对于 `source` 是本地路径的每个条目，它还验证该 plugin 自己的 `plugin.json`，并在条目的 `version` 与 `plugin.json` 中的版本不匹配时发出警告。在 plugin 的 `plugin.json` 中发现的问题以条目索引为前缀，形式为 `plugins[2] plugin.json →`。

从 Claude Code v2.1.196 开始，每个条目的检查还会：

* 包括 `source` 为 `.` 的 plugins
* 在 `marketplace.json` 位于 `.claude-plugin` 目录外时运行，针对文件自己的目录解析源
* 即使文件的另一部分有 schema 错误，也报告每个条目的问题

早期版本跳过 marketplace 根目录中的 plugins，仅从 `.claude-plugin/marketplace.json` 开始下降。

要验证单个 plugin 的 `plugin.json` 及其 skill、agent、command 和 hook 文件，请针对 plugin 目录本身运行该命令，例如 `claude plugin validate ./plugins/my-plugin`。常见错误：

| 错误                                                | 原因                                 | 解决方案                                                                  |
| :------------------------------------------------ | :--------------------------------- | :-------------------------------------------------------------------- |
| `File not found: .claude-plugin/marketplace.json` | 缺少 manifest                        | 使用必需字段创建 `.claude-plugin/marketplace.json`                            |
| `Invalid JSON syntax: Unexpected token...`        | marketplace.json 中的 JSON 语法错误      | 检查缺少的逗号、多余的逗号或未引用的字符串                                                 |
| `Duplicate plugin name "x" found in marketplace`  | 两个 plugins 共享相同的名称                 | 给每个 plugin 一个唯一的 `name` 值                                             |
| `plugins[0].source: Path contains ".."`           | 源路径包含 `..`                         | 使用相对于 marketplace 根目录的路径，不包含 `..`。见[相对路径](#relative-paths)            |
| `YAML frontmatter failed to parse: ...`           | skill、agent 或 command 文件中的 YAML 无效 | 修复 frontmatter 块中的 YAML 语法。在运行时，此文件加载时不带元数据。仅在验证 plugin 目录时报告         |
| `Invalid JSON syntax: ...`（hooks.json）            | 格式错误的 `hooks/hooks.json`           | 修复 JSON 语法。格式错误的 `hooks/hooks.json` 会阻止整个 plugin 加载。仅在验证 plugin 目录时报告 |

**警告**（非阻止）：

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

<h3 id="plugin-installation-failures">
  Plugin 安装失败
</h3>

**症状**：Marketplace 出现但 plugin 安装失败

**解决方案**：

* 验证 plugin 源 URL 是否可访问
* 检查 plugin 目录是否包含必需的文件
* 对于 GitHub 源，确保存储库是公开的或你有访问权限
* 通过手动克隆/下载来测试 plugin 源
* 如果源同时固定了 `ref` 和 `sha`，删除的上游分支或标签不会阻止大多数 git 主机（包括 GitHub、GitLab 和 Bitbucket）上的安装。在不支持通过 SHA 获取提交的服务器上（如 AWS CodeCommit），`ref` 必须仍然存在，固定的提交必须可从其到达。如果安装仍然失败，请确认固定的提交仍然存在于存储库中

<h3 id="private-repository-authentication-fails">
  私有存储库身份验证失败
</h3>

**症状**：从私有存储库安装 plugins 时出现身份验证错误

**解决方案**：

对于手动安装和更新：

* 验证你已使用你的 git 提供商进行身份验证（例如，对于 GitHub 运行 `gh auth status`）
* 检查你的凭证助手是否配置正确：`git config --global credential.helper`
* 尝试手动克隆存储库以验证你的凭证有效

对于后台自动更新：

* 默认情况下，后台刷新会为拉取禁用 git 凭证助手，因此拉取无法通过 HTTPS 进行身份验证。在 `ssh-agent` 中加载了密钥的 SSH 远程仍然可以进行身份验证。失败的拉取会触发从头重新克隆，这使用你存储的凭证，但在大型存储库上可能超时
* 设置 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在后台拉取失败时保留现有克隆
* 配置 git 凭证助手，例如 `gh auth setup-git`，以便重新克隆回退可以进行身份验证
* 如果重新克隆在大型存储库上超时，请使用 [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out) 增加限制
* 配置一个 [git URL 重写](#private-repositories) 作用于 marketplace 存储库，以便后台拉取直接进行身份验证
* 或使用 `/plugin marketplace update <name>` 手动更新私有 marketplaces，这使用你的凭证

<h3 id="marketplace-updates-fail-in-offline-environments">
  Marketplace 更新在离线环境中失败
</h3>

**症状**：Marketplace `git pull` 在后台失败，Claude Code 反复尝试无法成功的重新克隆。

**原因**：默认情况下，当 `git pull` 失败时，Claude Code 会尝试从头重新克隆。在离线或隔离的环境中，重新克隆以相同的方式失败，之后对先前缓存的恢复是尽力而为的。刷新在启动后在后台运行，因此不会延迟启动，但每个会话都会重复失败的尝试，每个 git 操作都可以等待 [120 秒超时](#git-operations-time-out)。

**解决方案**：设置 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在拉取失败时跳过重新克隆尝试并继续使用现有缓存：

```bash theme={null}
export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1
```

设置此变量后，Claude Code 在 `git pull` 失败时保留陈旧的 marketplace 克隆，并继续使用最后已知的良好状态。对于存储库永远无法访问的完全离线部署，请改用 [`CLAUDE_CODE_PLUGIN_SEED_DIR`](#pre-populate-plugins-for-containers) 在构建时预填充 plugins 目录。

<h3 id="git-operations-time-out">
  Git 操作超时
</h3>

**症状**：Plugin 安装或 marketplace 更新失败，出现超时错误，如"Git clone timed out after 120s"或"Git pull timed out after 120s"。

**原因**：Claude Code 对所有 git 操作使用 120 秒超时，包括克隆 plugin 存储库和拉取 marketplace 更新。大型存储库或缓慢的网络连接可能超过此限制。

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

```bash theme={null}
export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 minutes
```

<h3 id="plugins-with-relative-paths-fail-in-url-based-marketplaces">
  相对路径 Plugins 在基于 URL 的 Marketplaces 中失败
</h3>

**症状**：通过 URL（如 `https://example.com/marketplace.json`）添加了 marketplace，但具有相对路径源（如 `"./plugins/my-plugin"`）的 plugins 无法安装，出现"path not found"错误。

**原因**：基于 URL 的 marketplaces 仅下载 `marketplace.json` 文件本身。它们不从服务器下载 plugin 文件。marketplace 条目中的相对路径引用远程服务器上未下载的文件。

**解决方案**：

* **使用外部源**：将 plugin 条目更改为使用 GitHub、npm 或 git URL 源而不是相对路径：
  ```json theme={null}
  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
  ```
* **使用基于 Git 的 Marketplace**：在 Git 存储库中托管你的 marketplace 并使用 git URL 添加它。基于 Git 的 marketplaces 克隆整个存储库，使相对路径有效。

<h3 id="files-not-found-after-installation">
  安装后文件未找到
</h3>

**症状**：Plugin 安装但对文件的引用失败，特别是 plugin 目录外的文件

**原因**：Plugins 被复制到缓存目录而不是就地使用。引用 plugin 目录外文件的路径（如 `../shared-utils`）不会工作，因为这些文件不会被复制。

**解决方案**：见 [Plugin 缓存和文件解析](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution) 了解解决方法，包括符号链接和目录重组。

有关其他调试工具和常见问题，请参阅[调试和开发工具](/docs/zh-CN/plugins-reference#debugging-and-development-tools)。

<h2 id="see-also">
  另见
</h2>

* [发现和安装预构建的 plugins](/docs/zh-CN/discover-plugins) - 从现有 marketplaces 安装 plugins
* [Plugins](/docs/zh-CN/plugins) - 创建你自己的 plugins
* [Plugins 参考](/docs/zh-CN/plugins-reference) - 完整的技术规范和架构
* [Plugin 设置](/docs/zh-CN/settings#plugin-settings) - Plugin 配置选项
* [strictKnownMarketplaces 参考](/docs/zh-CN/settings#strictknownmarketplaces) - 托管 marketplace 限制