Claude Code: 插件系统
最后更新：2026-08-31
插件让 Claude Code 的能力可插拔扩展——安装一个插件，就多一种能力，不需要改核心代码。
💡 提示：Claude Code 的插件和 MCP 是两种不同的扩展方式。插件修改 Claude Code 本身的行为，MCP 扩展它连接外部世界的能力。
📋 前置知识：第十三章 子代理
1. 你将学到
- 插件系统架构
- 官方与社区插件
- 插件安装与管理
- 插件开发入门
- 插件与 MCP 的区别
2. 插件系统架构
(1) 插件类型
| 类型 | 作用 | 示例 |
|---|---|---|
| 工具插件 | 添加新工具/命令 | 代码分析工具 |
| 钩子插件 | 在特定事件触发自定义行为 | 提交前自动 lint |
| 主题插件 | 改变输出样式 | 彩色 diff 显示 |
| 集成插件 | 连接第三方服务 | Jira 集成 |
(2) 插件生命周期
graph LR
A[发现插件] --> B[安装插件]
B --> C[加载配置]
C --> D[注册工具/钩子]
D --> E[运行时调用]
E --> F[卸载/禁用]
(3) 插件与 MCP 对比
| 维度 | 插件 | MCP |
|---|---|---|
| 扩展方向 | 修改 Claude Code 行为 | 连接外部服务 |
| 运行位置 | Claude Code 进程内 | 独立进程 |
| 通信方式 | 直接函数调用 | 协议通信 |
| 适用场景 | 添加命令、改变输出 | 数据库、API、浏览器 |
| 开发难度 | 中 | 低 |
3. 官方与社区插件
(1) 官方插件
| 插件 | 功能 | 安装 |
|---|---|---|
| claude-plugin-lint | 自动 lint 修改的文件 | claude plugin add lint |
| claude-plugin-test | 修改后自动运行测试 | claude plugin add test |
| claude-plugin-git | 增强集成 git 操作 | claude plugin add git |
| claude-plugin-doc | 自动生成文档 | claude plugin add doc |
(2) 社区插件
| 插件 | 功能 | 来源 |
|---|---|---|
| claude-plugin-jira | Jira Issue 集成 | GitHub |
| claude-plugin-slack | Slack 通知 | GitHub |
| claude-plugin-docker | Docker 操作增强 | GitHub |
| claude-plugin-terraform | IaC 代码审查 | GitHub |
▶ 示例 1: 插件安装与管理
BASH
# 查看已安装插件
claude plugin list
# 安装官方插件
claude plugin add lint
# 安装社区插件（从 npm）
claude plugin add @community/claude-plugin-jira
# 安装本地插件
claude plugin add ./my-custom-plugin
# 禁用插件（不卸载）
claude plugin disable lint
# 卸载插件
claude plugin remove lint
# 更新插件
claude plugin update
4. 插件配置
(1) 全局配置
JSON
// ~/.claude/plugins.json
{
"plugins": [
{
"name": "lint",
"enabled": true,
"config": {
"runOnSave": true,
"fix": true
}
},
{
"name": "test",
"enabled": true,
"config": {
"watchMode": false,
"coverage": true
}
}
]
}
(2) 项目级配置
JSON
// .claude/plugins.json
{
"plugins": [
{
"name": "lint",
"config": {
"command": "npm run lint:fix",
"files": ["src/**/*.ts"]
}
}
]
}
▶ 示例 2: Lint 插件工作流
TEXT
📖 仅展示
# 安装 lint 插件后
> 重构 src/utils/string.ts 中的 slugify 函数
Claude Code:
→ Reading src/utils/string.ts
→ Modifying slugify function...
→ [lint plugin] Running: npm run lint -- --fix
→ [lint plugin] Found 1 issue: missing return type
→ Auto-fixing: adding string return type
→ [lint plugin] All clean ✓
→ Running: npm test -- string.test.ts
✅ All tests passed
5. 插件开发入门
(1) 插件结构
TEXT
📖 仅展示
my-plugin/
├── package.json
├── index.ts
├── README.md
└── config.schema.json
▶ 示例 3: 创建简单插件
TYPESCRIPT
// my-plugin/index.ts
interface ClaudePlugin {
name: string;
version: string;
tools?: ToolDefinition[];
hooks?: HookDefinition[];
}
export default {
name: "my-custom-linter",
version: "1.0.0",
hooks: {
"after:file:write": async (context) => {
const { filePath, content } = context;
if (filePath.endsWith(".ts")) {
const { execSync } = require("child_process");
try {
execSync(`npx eslint --fix ${filePath}`, { stdio: "pipe" });
console.log(`[my-linter] Fixed ${filePath}`);
} catch (e) {
console.log(`[my-linter] Issues in ${filePath}`);
}
}
},
},
tools: [
{
name: "count_lines",
description: "Count lines of code in a file",
parameters: {
file: { type: "string", description: "File path" },
},
execute: async ({ file }) => {
const fs = require("fs");
const content = fs.readFileSync(file, "utf-8");
return { lines: content.split("\n").length };
},
},
],
} as ClaudePlugin;
6. 插件最佳实践
(1) 选择插件的原则
| 原则 | 说明 |
|---|---|
| 最小化 | 只安装必要的插件 |
| 验证来源 | 优先官方，社区需审查 |
| 测试先行 | 新插件先在测试项目验证 |
| 定期清理 | 删除不用的插件 |
(2) 插件冲突处理
TEXT
📖 仅展示
# 多个插件可能产生冲突
lint 插件: 保存后运行 eslint --fix
format 插件: 保存后运行 prettier --write
# 解决：在配置中指定执行顺序
{
"plugins": [
{ "name": "format", "order": 1 },
{ "name": "lint", "order": 2 }
]
}
❓ 常见问题
Q 插件和 MCP 到底用哪个？
A 连接外部服务用 MCP（数据库、GitHub），修改 Claude Code 行为用插件（自动 lint、自定义命令）。两者可以同时使用。
Q 安装太多插件会拖慢 Claude Code 吗？
A 会。每个插件占用加载时间和内存。建议只安装必要的，定期清理。
Q 插件会影响 API 费用吗？
A 间接影响。某些插件可能增加上下文大小或触发额外 API 调用。但通常影响很小。
Q 社区插件安全吗？
A 不保证。安装前检查源码和作者信誉。优先使用有较多 star 和活跃维护的插件。
Q 能同时安装多个同类插件吗？
A 可以但可能冲突。两个 lint 插件可能对同一文件执行不同规则。建议同类插件只保留一个。
Q 插件开发难吗？
A 简单插件只需几十行代码。遵循插件接口规范，定义工具或钩子即可。复杂插件需要深入理解 Claude Code 的内部事件系统。
📖 小节
- 插件扩展 Claude Code 的行为，MCP 扩展连接能力
- 官方插件：lint、test、git、doc
- 通过
claude plugin add/remove管理插件 - 插件开发：定义工具和钩子，遵循接口规范
- 最小化原则，只安装必要插件
📝 作业
- 基础题（难度⭐）：安装官方 lint 插件，验证修改文件后自动 lint 功能。
- 进阶题（难度⭐⭐）：安装并配置两个插件，确保它们不冲突。
- 挑战题（难度⭐⭐⭐）：开发一个自定义插件，在每次文件修改后自动运行格式化和 lint。
