{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后进一步探索。

# 创建和分发插件市场

> 构建和托管插件市场，向团队和社区分发 Claude Code 扩展。

**插件市场**是一个目录，让你可以向他人分发插件。市场提供集中发现、版本跟踪、自动更新，并支持多种源类型（git 仓库、本地路径等）。本指南展示如何创建你自己的市场以与团队或社区分享插件。

想要从现有市场安装插件？请参阅[发现和安装预构建插件](/en/discover-plugins)。

## 概述

创建和分发市场涉及：

1. **创建插件**：构建一个或多个带有技能、代理、hooks、MCP 服务器或 LSP 服务器的插件。本指南假设你已有要分发的插件；关于如何创建它们，请参阅[创建插件](/en/plugins)。
2. **创建市场文件**：定义一个 `marketplace.json` 来列出你的插件及其位置（参阅[创建市场文件](#create-the-marketplace-file)）。
3. **托管市场**：推送到 GitHub、GitLab 或其他 git 主机（参阅[托管和分发市场](#host-and-distribute-marketplaces)）。
4. **与用户分享**：用户使用 `/plugin marketplace add` 添加你的市场并安装单个插件（参阅[发现和安装插件](/en/discover-plugins)）。

市场上线后，你可以通过向仓库推送更改来更新它。用户使用 `/plugin marketplace update` 刷新其本地副本。

## 演练：创建本地市场

本示例创建一个带有一个插件的市场：用于代码审查的 `quality-review` 技能。你将创建目录结构，添加技能，创建插件清单和市场目录，然后安装并测试它。

<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="创建技能">
    创建定义 `quality-review` 技能功能的 `SKILL.md` 文件。

    ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}
    ---
    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.
    ```
  </Step>

  <Step title="创建插件清单">
    创建描述插件的 `plugin.json` 文件。清单放在 `.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 中，每次提交自动计为新版本。参阅[版本解析](#version-resolution-and-release-channels)选择正确的方法。
    </Note>
  </Step>

  <Step title="创建市场文件">
    创建列出你插件的市场目录。

    ```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="添加并安装">
    添加市场并安装插件。

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

  <Step title="试用">
    在编辑器中选择一些代码并运行你的新技能。插件技能按插件名称命名空间化。

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

要了解插件的更多功能（包括 hooks、代理、MCP 服务器和 LSP 服务器），请参阅[插件](/en/plugins)。

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

  如果你需要在插件之间共享文件，请使用符号链接。详情请参阅[插件缓存和文件解析](/en/plugins-reference#plugin-caching-and-file-resolution)。
</Note>

## 创建市场文件

在你的仓库根目录创建 `.claude-plugin/marketplace.json`。此文件定义你市场的名称、所有者信息以及插件列表及其来源。

每个插件条目至少需要 `name` 和 `source`（从中获取的位置）。关于所有可用字段，请参阅下方的[完整 schema](#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"
    }
  ]
}
```

## 市场 schema

### 必需字段

| 字段     | 类型   | 描述                                                                                                                                                            | 示例        |
| :-------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |
| `name`    | string | 市场标识符（kebab-case，无空格）。这是面向用户的：用户在安装插件时看到它（例如 `/plugin install my-tool@your-marketplace`）。 | `"acme-tools"` |
| `owner`   | object | 市场维护者信息（[参阅下方字段](#owner-fields)）                                                                                                 |                |
| `plugins` | array  | 可用插件列表                                                                                                                                              | 参见下文      |

<Note>
  **保留名称**：以下市场名称保留给 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`）也会被阻止。
</Note>

### 所有者字段

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

### 可选字段

| 字段                                 | 类型   | 描述                                                                                                                                                                                                                                                        |
| :------------------------------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$schema`                             | string | 用于编辑器自动完成和验证的 JSON Schema URL。Claude Code 在加载时忽略此字段。                                                                                                                                                               |
| `description`                         | string | 简要市场描述                                                                                                                                                                                                                                      |
| `version`                             | string | 市场清单版本                                                                                                                                                                                                                                       |
| `metadata.pluginRoot`                 | string | 前置到相对插件源路径的基础目录（例如 `"./plugins"` 让你可以写 `"source": "formatter"` 而非 `"source": "./plugins/formatter"`）                                                                                          |
| `allowCrossMarketplaceDependenciesOn` | array  | 此市场中的插件可以依赖的其他市场。来自未列在此处的市场的依赖在安装时会被阻止。参阅[依赖另一个市场的插件](/en/plugin-dependencies#depend-on-a-plugin-from-another-marketplace)。 |

`description` 和 `version` 也可以放在 `metadata` 下以保持向后兼容。

## 插件条目

`plugins` 数组中的每个插件条目描述一个插件及其位置。你可以包含[插件清单 schema](/en/plugins-reference#plugin-manifest-schema) 中的任何字段（如 `description`、`version`、`author`、`commands`、`hooks` 等），以及这些市场特定字段：`source`、`category`、`tags` 和 `strict`。

### 必需字段

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

### 可选插件字段

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

| 字段         | 类型    | 描述                                                                                                                                                                                                                                         |
| :------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `displayName` | string  | {/* min-version: 2.1.143 */}在 UI 界面中显示的人类可读名称。省略时回退到 `name`。可以包含空格和任何大小写。不用于命名空间或查找。需要 Claude Code v2.1.143 或更高版本。                             |
| `description` | string  | 简要插件描述                                                                                                                                                                                                                            |
| `version`     | string  | 插件版本。如果设置（此处或 `plugin.json` 中），插件固定到此字符串，用户仅在它更改时接收更新。省略则回退到 git commit SHA。参阅[版本解析](#version-resolution-and-release-channels)。 |
| `author`      | object  | 插件作者信息（`name` 必需，`email` 可选）                                                                                                                                                                                       |
| `homepage`    | string  | 插件主页或文档 URL                                                                                                                                                                                                                |
| `repository`  | string  | 源代码仓库 URL                                                                                                                                                                                                                          |
| `license`     | string  | SPDX 许可证标识符（例如 MIT、Apache-2.0）                                                                                                                                                                                              |
| `keywords`    | array   | 用于插件发现和分类的标签                                                                                                                                                                                                        |
| `category`    | string  | 用于组织的插件类别                                                                                                                                                                                                                    |
| `tags`        | array   | 用于可搜索性的标签                                                                                                                                                                                                                              |
| `strict`      | boolean | 控制 `plugin.json` 是否是组件定义的权威来源（默认：true）。参阅下方[严格模式](#strict-mode)。                                                                                                                   |

**组件配置字段：**

| 字段        | 类型           | 描述                                                    |
| :----------- | :------------- | :------------------------------------------------------------- |
| `skills`     | string\|array  | 包含 `<name>/SKILL.md` 的技能目录的自定义路径 |
| `commands`   | string\|array  | 扁平 `.md` 技能文件或目录的自定义路径          |
| `agents`     | string\|array  | 代理文件的自定义路径                                    |
| `hooks`      | string\|object | 自定义 hooks 配置或 hooks 文件路径               |
| `mcpServers` | string\|object | MCP 服务器配置或 MCP 配置路径                |
| `lspServers` | string\|object | LSP 服务器配置或 LSP 配置路径                |

## 插件源

插件源告诉 Claude Code 在哪里获取你市场中列出的每个插件。它们在 `marketplace.json` 中每个插件条目的 `source` 字段中设置。

插件克隆或复制到本地机器后，它会被复制到 `~/.claude/plugins/cache` 中的本地版本化插件缓存。

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

<Note>
  **市场源与插件源**：这些是控制不同事物的不同概念。

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

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

### 相对路径

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

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

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

<Note>
  相对路径仅在用户通过 Git（GitHub、GitLab 或 git URL）添加你的市场时有效。如果用户通过 `marketplace.json` 文件的直接 URL 添加你的市场，相对路径将无法正确解析。对于基于 URL 的分发，请改用 GitHub、npm 或 git URL 源。详情请参阅[故障排除](#plugins-with-relative-paths-fail-in-url-based-marketplaces)。
</Note>

### GitHub 仓库

```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 commit SHA，用于固定到精确版本 |

### Git 仓库

```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 commit SHA，用于固定到精确版本                                                                                    |

### Git 子目录

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

```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 | 必需。仓库中包含插件的子目录路径（例如 `"tools/claude-plugin"`） |
| `ref`  | string | 可选。Git 分支或标签（默认为仓库默认分支）                                      |
| `sha`  | string | 可选。完整的 40 字符 git commit SHA，用于固定到精确版本                                    |

### npm 包

以 npm 包分发的插件使用 `npm install` 安装。这适用于公共 npm 注册表或你的团队托管的私有注册表上的任何包。

```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` 字段：

```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 注册表 URL。默认为系统 npm 注册表（通常为 npmjs.org） |

### 高级插件条目

本示例展示了使用多个可选字段的插件条目，包括命令、代理、hooks 和 MCP 服务器的自定义路径：

```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`**：你可以指定多个目录或单个文件。路径相对于插件根目录。
* **`${CLAUDE_PLUGIN_ROOT}`**：在 hooks 和 MCP 服务器配置中使用此变量引用插件安装目录内的文件。这是必要的，因为插件安装时会被复制到缓存位置。对于应该在插件更新中保留的依赖或状态，请改用 [`${CLAUDE_PLUGIN_DATA}`](/en/plugins-reference#persistent-data-directory)。
* **`strict: false`**：由于设置为 false，插件不需要自己的 `plugin.json`。市场条目定义一切。参阅下方[严格模式](#strict-mode)。

### 严格模式

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

| 值            | 行为                                                                                                                                                         |
| :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `true`（默认） | `plugin.json` 是权威来源。市场条目可以用额外组件补充它，两个源会合并。                                 |
| `false`          | 市场条目就是完整定义。如果插件也有声明组件的 `plugin.json`，则会产生冲突，插件加载失败。 |

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

* **`strict: true`**：插件有自己的 `plugin.json` 并管理自己的组件。市场条目可以在其上添加额外的技能或 hooks。这是默认值，适用于大多数插件。
* **`strict: false`**：市场运营商想要完全控制。插件仓库提供原始文件，市场条目定义哪些文件作为技能、代理、hooks 等暴露。当市场以不同于插件作者意图的方式重组或策展插件组件时很有用。

## 托管和分发市场

### 在 GitHub 上托管（推荐）

GitHub 提供最简单的分发方法：

1. **创建仓库**：为你的市场设置新仓库
2. **添加市场文件**：使用你的插件定义创建 `.claude-plugin/marketplace.json`
3. **与团队分享**：用户使用 `/plugin marketplace add owner/repo` 添加你的市场

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

### 在其他 git 服务上托管

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

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

### 私有仓库

Claude Code 支持从私有仓库安装插件。对于手动安装和更新，Claude Code 使用你现有的 git 凭据助手，因此通过 `gh auth login`、macOS 钥匙串或 `git-credential-store` 的 HTTPS 访问与终端中的工作方式相同。SSH 访问只要主机已在你的 `known_hosts` 文件中且密钥已加载到 `ssh-agent` 中即可工作，因为 Claude Code 会抑制主机指纹和密钥密码的交互式 SSH 提示。

后台自动更新在启动时运行，不使用凭据助手，因为交互式提示会阻止 Claude Code 启动。要为私有市场启用自动更新，在你的环境中设置适当的认证令牌：

| 提供商  | 环境变量        | 说明                                     |
| :-------- | :--------------------------- | :---------------------------------------- |
| GitHub    | `GITHUB_TOKEN` 或 `GH_TOKEN` | 个人访问令牌或 GitHub App 令牌 |
| GitLab    | `GITLAB_TOKEN` 或 `GL_TOKEN` | 个人访问令牌或项目令牌    |
| Bitbucket | `BITBUCKET_TOKEN`            | 应用密码或仓库访问令牌   |

在你的 shell 配置（例如 `.bashrc`、`.zshrc`）中设置令牌，或在运行 Claude Code 时传递它：

```bash theme={null}
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
```

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

### 分发前在本地测试

分享前在本地测试你的市场：

```shell theme={null}
/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace
```

关于完整的添加命令（GitHub、Git URL、本地路径、远程 URL），请参阅[添加市场](/en/discover-plugins#add-marketplaces)。

### 为你的团队要求市场

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

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

你也可以指定默认启用哪些插件：

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

关于完整的配置选项，请参阅[插件设置](/en/settings#plugin-settings)。

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

### 为容器预填充插件

对于容器镜像和 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` 为你的目标种子路径，以便插件直接安装到那里：

```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` 中找到的市场注册到主配置中，并直接使用 `cache/` 下找到的插件缓存而不重新克隆。这在交互模式和使用 `-p` 标志的非交互模式下都有效。

行为详情：

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

### 托管市场限制

对于需要严格控制插件源的组织，管理员可以使用托管设置中的 [`strictKnownMarketplaces`](/en/settings#strictknownmarketplaces) 设置限制用户允许添加哪些插件市场。

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

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

#### 常见配置

禁用所有市场添加：

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

仅允许特定市场：

```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 服务器的所有市场，使用主机上的正则表达式模式匹配。这是 [GitHub Enterprise Server](/en/github-enterprise-server#plugin-marketplaces-on-ghes) 或自托管 GitLab 实例的推荐方法：

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

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

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

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

<Note>
  `strictKnownMarketplaces` 限制用户可以添加什么，但不会自行注册市场。要使允许的市场自动可用而无需用户运行 `/plugin marketplace add`，将其与同一 `managed-settings.json` 中的 [`extraKnownMarketplaces`](/en/settings#extraknownmarketplaces) 配对。参阅[同时使用两者](/en/settings#strictknownmarketplaces)。
</Note>

#### 限制工作原理

限制在任何网络或文件系统操作之前检查。检查在市场添加和插件安装、更新、刷新和自动更新时运行。如果市场在策略配置之前添加且其源不再匹配允许列表，Claude Code 拒绝从中安装或更新插件。`blockedMarketplaces` 的执行方式相同。

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

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

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

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

关于完整的配置详情（包括所有支持的源类型和与 `extraKnownMarketplaces` 的比较），请参阅 [strictKnownMarketplaces 参考](/en/settings#strictknownmarketplaces)。

### 版本解析和发布渠道

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

Claude Code 从以下设置的第一个解析插件版本：

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

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

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

  避免在 `plugin.json` 和市场条目中同时设置 `version`。`plugin.json` 值始终静默优先，因此过期的清单版本可能掩盖你在 `marketplace.json` 中设置的版本。
</Warning>

#### 设置发布渠道

要为你的插件支持"stable"和"latest"发布渠道，你可以设置两个指向同一仓库不同 ref 或 SHA 的市场。然后可以通过[托管设置](/en/settings#settings-files)将两个市场分配给不同的用户组。

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

##### 示例

```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"
      }
    }
  ]
}
```

##### 将渠道分配给用户组

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

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

early-access 组接收 `latest-tools`：

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

#### 固定依赖版本

插件可以将其依赖约束到 semver 范围，以便依赖更新不会破坏依赖插件。参阅[约束插件依赖版本](/en/plugin-dependencies)了解 `{plugin-name}--v{version}` git-tag 约定、范围语法以及同一依赖上的多个约束如何组合。

## 验证和测试

分享前测试你的市场。

验证你的市场 JSON 语法：

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

或在 Claude Code 中：

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

添加市场进行测试：

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

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

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

关于完整的插件测试工作流，请参阅[在本地测试你的插件](/en/plugins#test-your-plugins-locally)。关于技术故障排除，请参阅[插件参考](/en/plugins-reference)。

## 从 CLI 管理市场

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

### Plugin marketplace add

从 GitHub 仓库、git URL、远程 URL 或本地路径添加市场。

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

**参数：**

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

**选项：**

| 选项                | 描述                                                                                                                                         | 默认值 |
| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
| `--scope <scope>`     | 声明市场的位置：`user`、`project` 或 `local`。参阅[插件安装范围](/en/plugins-reference#plugin-installation-scopes) | `user`  |
| `--sparse <paths...>` | 通过 git sparse-checkout 限制检出到特定目录。对 monorepo 很有用                                                                |         |

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

```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
```

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

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

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

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

### Plugin marketplace list

列出所有已配置的市场。

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

**选项：**

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

### Plugin marketplace remove

移除已配置的市场。也接受别名 `rm`。

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

**参数：**

* `<name>`：要移除的市场名称，如 `claude plugin marketplace list` 所示。这是 `marketplace.json` 中的 `name`，而非你传递给 `add` 的源

<Warning>
  移除市场也会卸载你从中安装的所有插件。要在不丢失已安装插件的情况下刷新市场，请改用 `claude plugin marketplace update`。
</Warning>

### Plugin marketplace update

从源刷新市场以获取新插件和版本更改。

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

**参数：**

* `[name>`：要更新的市场名称，如 `claude plugin marketplace list` 所示。省略则更新所有市场

`remove` 和 `update` 在对种子管理的市场运行时都会失败，因为它是只读的。更新所有市场时，种子管理的条目会被跳过，其他市场仍会更新。要更改种子提供的插件，请请管理员更新种子镜像。参阅[为容器预填充插件](#pre-populate-plugins-for-containers)。

## 故障排除

### 市场未加载

**症状**：无法添加市场或从中看到插件

**解决方案**：

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

### 市场验证错误

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

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

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

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

* `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` 在拉取失败时保留现有缓存而非清除它：

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

设置此变量后，Claude Code 在 `git pull` 失败时保留过期的市场克隆并继续使用最后已知的良好状态。对于完全离线部署（仓库永远不可达），使用 [`CLAUDE_CODE_PLUGIN_SEED_DIR`](#pre-populate-plugins-for-containers) 在构建时预填充插件目录。

### Git 操作超时

**症状**：插件安装或市场更新因超时错误而失败，如"Git clone timed out after 120s"或"Git pull timed out after 120s"。

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

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

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

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

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

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

**解决方案**：

* **使用外部源**：将插件条目更改为使用 GitHub、npm 或 git URL 源而非相对路径：
  ```json theme={null}
  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
  ```
* **使用基于 Git 的市场**：将你的市场托管在 Git 仓库中并使用 git URL 添加它。基于 Git 的市场克隆整个仓库，使相对路径正常工作。

### 安装后找不到文件

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

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

**解决方案**：参阅[插件缓存和文件解析](/en/plugins-reference#plugin-caching-and-file-resolution)了解包括符号链接和目录重组在内的解决方法。

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

## 另请参阅

* [发现和安装预构建插件](/en/discover-plugins) - 从现有市场安装插件
* [插件](/en/plugins) - 创建你自己的插件
* [插件参考](/en/plugins-reference) - 完整技术规范和 schema
* [插件设置](/en/settings#plugin-settings) - 插件配置选项
* [strictKnownMarketplaces 参考](/en/settings#strictknownmarketplaces) - 托管市场限制