文档索引

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

创建和分发插件市场

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

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

想要从现有市场安装插件？请参阅发现和安装预构建插件。

概述

创建和分发市场涉及：

1. 创建插件：构建一个或多个带有技能、代理、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. 创建技能

   创建定义 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. 创建插件清单

   创建描述插件的 plugin.json 文件。清单放在 .claude-plugin/ 目录中。

   {
     "name": "quality-review-plugin",
     "description": "Adds a quality-review skill for quick code reviews",
     "version": "1.0.0"
   }
   

   ℹ️

   Note

   设置 version 意味着用户仅在你更改此字段时接收更新，因此每次发布时都要递增它。如果你省略 version 并将此市场托管在 git 中，每次提交自动计为新版本。参阅版本解析选择正确的方法。

4. 创建市场文件

   创建列出你插件的市场目录。

   {
     "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、代理、MCP 服务器和 LSP 服务器），请参阅插件。

创建市场文件

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

每个插件条目至少需要 name 和 source（从中获取的位置）。关于所有可用字段，请参阅下方的完整 schema。

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "[email protected]"
  },
  "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

必需字段

所有者字段

可选字段

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

插件条目

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

必需字段

可选插件字段

标准元数据字段：

组件配置字段：

插件源

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

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

相对路径

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

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

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

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（[email protected]:owner/repo.git）。

npm 包

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

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

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

{
  "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"
  }
}

高级插件条目

本示例展示了使用多个可选字段的插件条目，包括命令、代理、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": "[email protected]"
  },
  "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：你可以指定多个目录或单个文件。路径相对于插件根目录。
• {{CONTENT}}amp;#123;CLAUDE_PLUGIN_ROOT}：在 hooks 和 MCP 服务器配置中使用此变量引用插件安装目录内的文件。这是必要的，因为插件安装时会被复制到缓存位置。对于应该在插件更新中保留的依赖或状态，请改用 {{CONTENT}}amp;#123;CLAUDE_PLUGIN_DATA}。
• strict: false：由于设置为 false，插件不需要自己的 plugin.json。市场条目定义一切。参阅下方严格模式。

严格模式

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

何时使用每种模式：

• 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 添加：

/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 启动。要为私有市场启用自动更新，在你的环境中设置适当的认证令牌：

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

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

分发前在本地测试

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

/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
  }
}

关于完整的配置选项，请参阅插件设置。

为容器预填充插件

对于容器镜像和 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 会失败，并提示你请管理员更新种子镜像。
• 与设置组合：如果 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{{CONTENT}}quot;
    }
  ]
}

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

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

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

限制工作原理

限制在任何网络或文件系统操作之前检查。检查在市场添加和插件安装、更新、刷新和自动更新时运行。如果市场在策略配置之前添加且其源不再匹配允许列表，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，每次新提交都被视为新版本。这是内部或积极开发的插件最简单的设置。

设置发布渠道

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

示例

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

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

将渠道分配给用户组

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

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

early-access 组接收 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 命令。

Plugin marketplace add

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

claude plugin marketplace add <source> [options]

参数：

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

选项：

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

claude plugin marketplace add acme-corp/claude-plugins

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

claude plugin marketplace add acme-corp/[email protected]

从非 GitHub 主机的 git URL 添加：

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

Plugin marketplace list

列出所有已配置的市场。

claude plugin marketplace list [options]

选项：

Plugin marketplace remove

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

claude plugin marketplace remove <name>

参数：

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

Plugin marketplace update

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

claude plugin marketplace update [name]

参数：

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

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

故障排除

市场未加载

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

解决方案：

• 验证市场 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。常见错误：

警告（非阻塞）：

• 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 分钟

基于 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）将不起作用，因为这些文件未被复制。

解决方案：参阅插件缓存和文件解析了解包括符号链接和目录重组在内的解决方法。

关于其他调试工具和常见问题，请参阅调试和开发工具。

另请参阅

• 发现和安装预构建插件 - 从现有市场安装插件
• 插件 - 创建你自己的插件
• 插件参考 - 完整技术规范和 schema
• 插件设置 - 插件配置选项
• strictKnownMarketplaces 参考 - 托管市场限制