插件

本文你会学到：

• 🎯 什么是插件，以及它和「独立配置」的区别
• 🔧 如何安装、启用、禁用和卸载插件
• 📦 插件市场的概念和工作原理（官方市场 + 第三方市场 + 演示市场）
• ⚙️ 如何从零开发一个插件（含目录结构和 manifest 配置）
• 🧩 如何给插件添加组件（Hook、MCP、LSP、监视器、默认设置）
• 🚀 如何发布到官方市场，以及从独立配置迁移到插件
• 🔧 故障排除：常见插件问题的诊断与解决
• 🏷️ 插件的命名空间机制，以及为什么要做命名隔离

🔌 什么是插件¶

想象一下你的手机：出厂时系统功能有限，但通过应用商店安装 App 后，它能变成导航仪、支付工具、社交平台。Claude Code 的插件系统做的就是类似的事（v2.0.12 发布） —— 让你把 Skills、Hooks、MCP 服务器、LSP 服务器 等扩展功能打包成一个可分发、可版本管理的「扩展包」，一键安装到 Claude Code 中。

💡 简单来说：Plugin（插件）就是一个自包含的目录，里面装着各种扩展组件，附带一份描述文件（manifest）告诉 Claude Code 怎么加载它们。

插件能装什么¶

一个插件可以包含以下任意组合的组件：

插件 vs 独立配置¶

你可能会问：这些组件我也可以直接放在项目的 .claude/ 目录下，为什么要打包成插件？两者的区别如下：

📌 选择建议：个人快速实验用独立配置；需要分享给团队、社区，或者要在多个项目间复用，就用插件。

📥 安装与管理插件¶

插件的安装范围（Scope）¶

安装插件时，Claude Code 让你选择一个**安装范围**，决定插件在哪些地方生效、谁能使用：

安装插件¶

从市场安装插件最简单的方式：

1
2
3
4
5

# 从官方市场安装 GitHub 集成插件
/plugin install github@claude-plugins-official

# 通过 CLI 安装（指定范围）
claude plugin install formatter@my-marketplace --scope project

你也可以在交互界面操作：运行 /plugin，进入 Discover 标签页，选中插件后选择安装范围。

Installed 标签页改进（v2.1.110 改进）：Installed 视图现在会将需要关注的项和收藏项置顶，禁用的插件折叠隐藏。按 f 键可以收藏选中的插件，方便你快速找到常用的插件。

管理已安装的插件¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 禁用插件（不卸载，随时可重新启用）
/plugin disable plugin-name@marketplace-name

# 重新启用
/plugin enable plugin-name@marketplace-name

# 完全卸载
/plugin uninstall plugin-name@marketplace-name

# 保留数据卸载（适合测试新版本后重装）
claude plugin uninstall formatter@my-marketplace --keep-data

会话中热重载¶

安装、启用或禁用插件后，不需要重启 Claude Code。运行以下命令即可让所有改动立即生效（v2.1.69 新增 /reload-plugins 命令）：

1

/reload-plugins

Claude Code 会重新加载所有活跃的插件，并显示插件、Skills、Agents、Hooks、MCP 服务器和 LSP 服务器的数量统计。

清理孤立依赖¶

随着插件的安装和卸载，node_modules 中可能积累不再被任何插件使用的孤立依赖。v2.1.121 新增了清理命令：

1
2
3
4
5

# 移除所有孤立的自动安装插件依赖
claude plugin prune

# 卸载插件时自动级联清理
claude plugin uninstall plugin-name@marketplace --prune

当另一个插件的版本约束导致某个插件自动更新并被跳过时，/doctor 和 /plugin Errors 标签页会显示提示（v2.1.118 新增），方便你发现版本约束冲突。

插件错误处理与诊断¶

当插件依赖不满足时，Claude Code 会进行智能降级处理（v2.1.111 改进）：依赖错误现在区分冲突、无效和过于复杂的版本要求，给出更明确的错误提示。在 headless 模式下使用 --output-format stream-json 时，如果插件因依赖问题被降级，init 事件中会包含 plugin_errors 字段（v2.1.111 新增），方便自动化脚本检测和告警。

从 v2.1.113 起，plugin install 在依赖版本与已安装插件冲突时不再静默成功，而是**明确报告 range-conflict**——之前这种情况可能导致插件以错误版本被加载，行为难以排查。

🏪 插件市场¶

🔌 什么是插件市场¶

如果说插件是「App」，那插件市场就是「应用商店」。它本质上是一个**插件目录清单**，描述了有哪些插件可用、从哪里下载。使用插件市场的过程分两步：

1. 添加市场 —— 类似于「在手机上添加一个应用商店的源」
2. 从市场安装插件 —— 类似于「从商店里下载一个 App」

官方市场¶

Anthropic 维护了一个官方市场（名称为 claude-plugins-official），它在 Claude Code 启动时自动可用。你可以直接运行 /plugin 进入 Discover 标签页浏览，或者访问 claude.com/plugins 查看在线目录。

官方市场包含以下类别的插件：

代码智能（Code Intelligence）¶

这些插件为 Claude 接入语言服务器（Language Server），让它获得和 VS Code 一样的代码分析能力。安装插件并确保语言服务器二进制可用后，Claude 获得两项功能：

• 自动诊断：Claude 每次文件编辑后，语言服务器自动分析变更并报告类型错误、缺失导入和语法问题。如果引入了错误，Claude 会在同一轮中修复。当"发现诊断"指示器出现时，按 Ctrl+O 可内联查看诊断
• 代码导航：Claude 可以跳转到定义、查找引用、获取悬停类型信息、列出符号、查找实现和追踪调用层次结构——比基于 grep 的搜索更精确

⚠️ 安装 LSP 插件前，必须先确保对应的语言服务器二进制已安装并可用。以 TypeScript 为例：

1
2
3
4
5
6
7
8

# 1. 先安装语言服务器二进制
npm install -g typescript-language-server typescript

# 2. 验证安装
typescript-language-server --version

# 3. 再安装 LSP 插件
/plugin install typescript-lsp@claude-plugins-official

输出风格¶

自定义 Claude 的响应方式：

• explanatory-output-style：在回复中加入关于实现选择的教育性见解
• learning-output-style：交互式学习模式，帮助技能构建

外部集成¶

打包了预配置的 MCP 服务器，让 Claude 能直接连接外部服务：

• 源码管理：github、gitlab
• 项目管理：atlassian（Jira/Confluence）、asana、linear、notion
• 设计：figma
• 基础设施：vercel、firebase、supabase
• 通讯：slack
• 监控：sentry

开发工作流¶

为常见开发任务提供命令和代理：

• commit-commands：Git 提交工作流（commit、push、创建 PR）
• pr-review-toolkit：PR 审查专用代理
• agent-sdk-dev：使用 Claude Agent SDK 构建的工具
• plugin-dev：插件开发工具包

添加第三方市场¶

除了官方市场，任何人都可以创建和发布自己的市场。添加方式如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# 从 GitHub 仓库添加（owner/repo 格式）
/plugin marketplace add owner/repo

# 从其他 Git 托管平台添加（HTTPS 或 SSH）
/plugin marketplace add https://gitlab.com/company/plugins.git
/plugin marketplace add git@gitlab.com:company/plugins.git

# 指定分支或标签
/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0

# 从本地目录添加（适合开发测试）
/plugin marketplace add ./my-local-marketplace

# 从本地 marketplace.json 文件直接添加
/plugin marketplace add ./path/to/marketplace.json

# 从远程 URL 添加
/plugin marketplace add https://example.com/marketplace.json

基于 Git 的市场和基于 URL 的市场有一个重要区别：Git 市场会完整克隆仓库，插件中的相对路径（如引用仓库内的脚本文件）可以正常工作；而基于远程 URL 的市场只下载 marketplace.json 文件本身，如果插件定义中使用了相对路径，安装时可能出现「路径未找到」错误。遇到这种情况，建议改用 Git 方式添加。

💡 快捷方式：/plugin market 可以代替 /plugin marketplace，rm 可以代替 remove。

演示市场（anthropics/claude-code）¶

Anthropic 还维护一个演示市场（claude-code-plugins），包含展示插件系统功能的示例插件。需要手动添加：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 添加演示市场
/plugin marketplace add anthropics/claude-code

# 浏览并安装（如 commit-commands 插件）
/plugin install commit-commands@anthropics-claude-code

# 安装后重载生效
/reload-plugins

# 使用插件的命令（以插件名为命名空间）
/commit-commands:commit

管理市场¶

1
2
3
4
5
6
7
8

# 查看所有已添加的市场及其来源和状态
/plugin marketplace list

# 刷新市场列表（获取最新插件信息）
/plugin marketplace update marketplace-name

# 移除市场
/plugin marketplace remove marketplace-name

注意：移除市场时会**级联卸载**你从该市场安装的所有插件。如果你只是想停止使用某个市场但保留已安装的插件，建议先改为手动更新，再手动管理各插件。

你也可以通过交互式界面管理市场：运行 /plugin，进入 Marketplaces 标签页，可以查看市场列表、添加新市场、更新市场数据和删除市场。

自动更新¶

官方市场默认开启自动更新。你也可以为第三方市场手动开启：运行 /plugin -> Marketplaces -> 选择市场 -> 启用自动更新。

启动时如果检测到插件有更新，Claude Code 会提示你运行 /reload-plugins 来加载新版本。

通过环境变量精细控制自动更新行为：

1
2
3
4
5
6

# 完全禁用 Claude Code 和所有插件的自动更新
export DISABLE_AUTOUPDATER=1

# 禁用 Claude Code 自动更新，但保留插件自动更新
export DISABLE_AUTOUPDATER=1
export FORCE_AUTOUPDATE_PLUGINS=1

插件安全最佳实践¶

插件和市场是高度受信任的组件 —— 它们以你的用户权限运行，可以执行任意代码。在安装前请牢记以下几点：

• 审查插件来源：只从你信任的开发者或组织安装插件。检查插件的 homepage 或 repository 字段，了解其代码来源
• 检查市场配置：添加第三方市场前，确认市场维护者的可信度。市场本质上只是一个插件列表，里面的插件来自不同作者
• 关注安装范围：在 project 范围安装的插件会通过 Git 共享给所有协作者。安装前考虑团队成员是否都需要这个插件
• 利用托管限制：企业环境可以通过托管市场限制控制用户允许添加的市场，防止安装未经审核的插件
• 及时更新：保持插件和市场更新，以获取安全修复

团队市场配置¶

团队管理员可以在项目的 .claude/settings.json 中预配置市场，让团队成员在信任项目文件夹时自动提示安装：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

extraKnownMarketplaces 支持的 source 类型除了 github（owner/repo 格式），还可以是 git（任意 Git URL）或 url（远程 marketplace.json URL）。团队成员信任项目文件夹后，Claude Code 会检测到这些预配置的市场并提示安装。

如果团队希望某些插件在所有成员的项目中默认启用（不依赖成员手动操作），可以在同一个 settings.json 中搭配 enabledPlugins 使用，实现市场和插件的自动化配置。

🛠️ 插件开发基础¶

创建第一个插件¶

让我们从最简单的情况开始 —— 创建一个只有一个 Skill 的插件。

创建目录结构

1
2
3
4
5
6

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # 插件清单文件
└── skills/
    └── hello/
        └── SKILL.md       # 技能定义

编写 plugin.json（清单文件）

1
2
3
4
5

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "我的第一个 Claude Code 插件"
}

编写 SKILL.md

1
2
3
4
5
6
7
8

---
name: hello
description: 向用户打招呼，接受一个名字参数
---

根据用户提供的名字，生成一段友好的问候语。

如果用户传入 $ARGUMENTS，使用该名字；否则使用"世界"。

💡 $ARGUMENTS 是一个特殊变量，用于捕获用户调用技能时传入的参数。

本地测试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 使用 --plugin-dir 加载本地插件进行测试
claude --plugin-dir ./my-plugin

# 从 .zip 归档加载插件（v2.1.128 新增）
claude --plugin-dir ./my-plugin.zip

# 一次加载多个插件
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

# 测试技能
/my-plugin:hello Claude

💡 --plugin-dir 加载的本地插件与已安装的市场插件同名时，本地副本在该会话中优先（托管设置强制启用的市场插件除外）。修改插件后运行 /reload-plugins 即可热重载。

完整的插件目录结构¶

当你的插件包含更多组件时，目录结构会更丰富：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

enterprise-plugin/
├── .claude-plugin/           # 元数据目录
│   └── plugin.json           # 插件清单（可选，无则自动发现）
├── commands/                 # 斜杠命令（Markdown 文件）
│   ├── status.md
│   └── logs.md
├── agents/                   # 子代理定义
│   ├── security-reviewer.md
│   └── compliance-checker.md
├── skills/                   # Agent Skills
│   ├── code-review/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # Hook 配置
│   └── hooks.json
├── bin/                      # 可执行文件（添加到 PATH）
├── .mcp.json                # MCP 服务器配置
├── .lsp.json                # LSP 服务器配置
├── settings.json            # 默认设置
└── scripts/                 # 工具脚本

⚠️ 常见错误：把组件目录（如 commands/、agents/）放到 .claude-plugin/ 里面。正确做法是放在插件根目录，只有 plugin.json 属于 .claude-plugin/。

plugin.json 详解¶

清单文件是可选的 —— 如果不提供，Claude Code 会自动从默认目录发现组件，并用目录名作为插件名。但推荐总是提供一份 plugin.json，因为它携带了版本号、描述等元数据。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
  "name": "my-plugin",          // 必填：唯一标识符（kebab-case）
  "version": "1.2.0",           // 语义化版本号
  "description": "插件用途简述",
  "author": {
    "name": "作者名",
    "email": "author@example.com"
  },
  "homepage": "https://docs.example.com",
  "repository": "https://github.com/user/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "skills": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "lspServers": "./.lsp.json"
}

💡 commands、agents、skills 等路径字段可以**替换**默认目录位置。如果指定了这些字段，对应的默认目录就不会被扫描。想同时保留默认目录并添加额外路径，可以用数组形式："commands": ["./commands/", "./extras/deploy.md"]。

当 skills 使用 "skills": ["./"] 声明时，插件会扫描指定目录下的所有 Skill。此时 Skill 的调用名称取自 SKILL.md frontmatter 中的 name 字段而非目录名（v2.1.94 改进），这确保了 Skill 名称在不同安装方式下保持一致。

除了上述字段，plugin.json 还支持 monitors 键（2.1.105 新增）：

1
2
3
4
5

{
  "monitors": [
    { "script": "./scripts/monitor-logs.sh", "interval": 60 }
  ]
}

monitors 用于声明插件的后台监控脚本，Claude Code 会在插件激活时定期运行这些脚本，并将输出作为上下文注入对话。适合需要持续跟踪外部状态（如日志文件、服务健康）的插件。

两个重要的环境变量¶

Claude Code 为插件提供了两个特殊的环境变量，在 Hook 命令、MCP/LSP 配置、Skill 和 Agent 内容中都可以使用：

⚠️ ${CLAUDE_PLUGIN_ROOT} 在插件更新后会变化，不要在这里存放需要持久化的数据。需要跨版本保留的文件请用 ${CLAUDE_PLUGIN_DATA}。

给插件添加组件¶

给插件添加 Hook¶

在 hooks/hooks.json 中定义事件处理器：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

这会在 Claude 每次使用 Write 或 Edit 工具后自动运行格式化脚本。

给插件添加 MCP 服务器¶

在 .mcp.json 中配置 MCP 服务器：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    }
  }
}

给插件添加 LSP 服务器¶

对于官方市场没有覆盖的语言，可以通过 .lsp.json 添加自定义语言服务器配置：

1
2
3
4
5
6
7
8
9

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

⚠️ 安装插件的用户需要在其机器上安装对应的语言服务器二进制文件。

给插件添加后台监视器¶

后台监视器让插件在后台持续监控日志、文件或外部状态，当事件到达时通知 Claude。Claude Code 在插件激活时自动启动每个监视器。

1
2
3
4
5
6
7

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

command 的每行 stdout 输出在会话期间作为通知传递给 Claude。

插件默认设置¶

在插件根目录放置 settings.json 可以在插件启用时应用默认配置。目前支持以下键：

• agent：指定插件中某个 agent 作为主线程
• subagentStatusLine：控制子代理的状态行显示内容（如进度提示、任务摘要），让用户在主会话中能直观看到子代理的工作状态

1
2
3

{
  "agent": "security-reviewer"
}

这会激活插件 agents/ 目录中定义的 security-reviewer agent 作为主线程，应用其系统提示、工具限制和模型。settings.json 中的设置优先于 plugin.json 中声明的 settings。

发布到官方市场¶

当你的插件足够成熟，想分享给所有 Claude Code 用户时，可以通过以下入口提交：

• Claude.ai：claude.ai/settings/plugins/submit
• Console：platform.claude.com/plugins/submit

发布前的准备工作：

1. 完善 plugin.json：确保 name、version、description、repository 和 license 字段齐全。repository 应指向公开可访问的代码仓库，方便审核和用户审查源码
2. 准备 README.md：提供插件功能说明、安装步骤、配置方法和使用示例
3. 测试覆盖：使用 claude --plugin-dir ./my-plugin 本地验证所有组件正常工作
4. 版本号规范：遵循 Semantic Versioning（如 1.0.0），后续更新递增版本号

提交后 Anthropic 会审核你的插件。审核通过后，插件会出现在官方市场中，所有用户都可以通过 /plugin install <name>@claude-plugins-official 安装。官方市场的插件默认开启自动更新，用户无需手动操作即可获取你发布的后续版本。

如果你想独立分发插件（不通过官方市场），可以创建自己的市场并与用户共享。

从独立配置迁移到插件¶

如果你已经在 .claude/ 目录下积累了 Skills 或 Hooks，可以轻松迁移到插件：

📛 插件的命名空间¶

为什么需要命名空间¶

Claude Code 可能同时安装多个插件，如果两个插件都定义了一个叫 deploy 的 Skill，该怎么区分？答案就是命名空间。

每个插件的组件都会自动加上**插件名前缀**，格式为 插件名:组件名。例如：

• 插件 team-a-tools 中的 deploy 技能 -> /team-a-tools:deploy
• 插件 team-b-tools 中的 deploy 技能 -> /team-b-tools:deploy

这样即使两个插件有同名组件也不会冲突。这也是为什么插件名必须使用 kebab-case（如 my-plugin）—— 它会作为命名空间的前缀。

命名空间的具体体现¶

📌 总结：命名空间就是给每个插件的组件加了一个「姓氏」，确保全局唯一。虽然名字变长了，但换来的是多插件共存的稳定性 —— 这和 Java 的包名、Docker 的容器名是同样的设计思路。

🔧 故障排除¶

/plugin 命令无法识别¶

如果 /plugin 命令不出现：

1. 检查版本：运行 claude --version 确认版本支持插件
2. 更新 Claude Code：npm update -g @anthropic-ai/claude-code 或 brew upgrade claude-code
3. 重启 Claude Code：更新后重启终端

常见问题¶

代码智能常见问题¶

• 语言服务器未启动：验证二进制已安装且在 $PATH 中，检查 /plugin 错误标签页
• 高内存使用：rust-analyzer、pyright 等在大型项目上可能消耗大量内存，可临时禁用并改用内置搜索工具
• monorepo 误报诊断：工作区配置不正确时，语言服务器可能报告内部包的未解析导入错误——这不影响 Claude 编辑代码的能力