Plugin的开发环境搭建 - 学习笔记-Plugins

一、前置环境准备

1. Node.js 版本要求

Claude Code Plugin 基于 Node.js 运行时构建，官方推荐使用 Node.js 18.x LTS 或更高版本。建议安装最新的 LTS 版本以获得最佳稳定性和兼容性。可以通过以下命令检查当前 Node.js 版本：

node --version
npm --version

如果尚未安装 Node.js，建议通过 nvm（Node Version Manager）进行安装，这样可以方便地在不同版本之间切换：

# 安装 nvm（Windows 用户请使用 nvm-windows）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 安装并使用 Node.js LTS 版本
nvm install --lts
nvm use --lts

2. 包管理器配置

npm 会随 Node.js 一同安装，但也可以选择使用 yarn 或 pnpm 作为替代包管理器。每种管理器各有优势：npm 为官方默认工具，yarn 在依赖安装速度上更优，pnpm 则在磁盘空间利用上更为高效。建议团队项目统一使用同一种包管理器以避免锁文件冲突。

提示：如果使用 pnpm，需要在项目根目录创建 .npmrc 文件并添加 `shamefully-hoist=true` 配置，以确保所有依赖可以被正确解析。

3. Git 版本控制

Git 是 Plugin 开发中必不可少的版本管理工具。确保已安装 Git 2.30 以上版本，并完成基本配置：

git --version
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

4. 推荐 IDE 和编辑器配置

Visual Studio Code 是开发 Plugin 的首选 IDE，配合以下扩展可以大幅提升开发效率：ESLint（代码规范检查）、Prettier（代码格式化）、JSON Schema 验证插件（用于 manifest.json 智能提示）、npm IntelliSense（包导入自动补全）。建议在 VS Code 设置中开启自动保存和格式化功能。

二、Plugin 脚手架工具

1. 官方脚手架：create-claude-plugin

官方提供了 create-claude-plugin 脚手架工具，可以一键生成完整的 Plugin 项目结构。这是最推荐的方式，因为它会自动配置好所有必要的文件和依赖：

# 使用 npx 运行脚手架（无需全局安装）
npx create-claude-plugin my-plugin

# 进入项目目录
cd my-plugin

# 安装依赖
npm install

脚手架会引导你输入 Plugin 名称、描述、版本号等基本信息，然后自动生成包含完整目录结构和示例代码的项目。

2. 使用 npm init 手动创建

如果希望更灵活地控制项目结构，也可以使用 npm init 手动初始化项目：

mkdir my-plugin
cd my-plugin
npm init -y

这种方式会生成一个基础的 package.json 文件，后续所有结构和配置都需要手动添加。

3. 手动初始化项目目录

对于需要完全自定义的项目，可以按照以下步骤手动搭建目录结构：创建项目文件夹、编写 package.json（确保 type 字段设为 "module" 以支持 ES Module 语法）、安装核心依赖 @anthropic-ai/claude-code-plugin、添加 TypeScript 配置文件和 ESLint 配置文件。

最佳实践：首次开发 Plugin 时，强烈建议使用官方脚手架 create-claude-plugin。它已经处理好了大部分样板代码和配置，让你可以专注于 Plugin 的核心逻辑开发。熟悉流程后再根据项目需求进行手动定制。

三、开发目录初始化

1. 创建 Plugin 目录结构

一个标准的 Plugin 项目目录结构如下：

my-plugin/
├── src/
│   ├── index.js          # 主入口文件
│   ├── commands/         # 命令模块
│   │   └── hello.js
│   └── utils/            # 工具函数
│       └── helper.js
├── manifest.json         # Plugin 清单文件
├── package.json
├── tsconfig.json         # 如果使用 TypeScript
├── .gitignore
├── README.md
└── tests/
    └── index.test.js

2. 编写 manifest.json

manifest.json 是 Plugin 的核心配置文件，用于声明 Plugin 的元信息、功能入口和权限声明。以下是一个标准的 manifest.json 示例：

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My first Claude Code Plugin",
  "main": "src/index.js",
  "commands": [
    {
      "name": "hello",
      "description": "Say hello from plugin",
      "handler": "helloCommand"
    }
  ],
  "permissions": {
    "files": ["read", "write"],
    "network": false
  }
}

3. 创建主入口文件

主入口文件负责注册 Plugin 的所有命令和功能。以下是一个简单的主入口文件示例：

// src/index.js
import { definePlugin } from '@anthropic-ai/claude-code-plugin';

export default definePlugin({
  name: 'my-plugin',
  commands: {
    helloCommand: async (args, context) => {
      return {
        type: 'text',
        content: `Hello from my-plugin! Args: ${JSON.stringify(args)}`
      };
    }
  }
});

4. 安装开发依赖

根据项目需求安装必要的开发依赖：

# 核心依赖（必需）
npm install @anthropic-ai/claude-code-plugin

# 开发依赖（推荐）
npm install --save-dev eslint prettier jest

# TypeScript 支持（可选）
npm install --save-dev typescript @types/node

注意：@anthropic-ai/claude-code-plugin 包提供了 Plugin SDK，包含类型定义、工具函数和调试辅助功能。请确保始终使用最新版本。

四、本地加载和测试

1. 使用 npm link 本地链接 Plugin

在开发阶段，可以通过 npm link 将 Plugin 链接到全局，方便 Claude Code 加载和测试：

# 在 Plugin 项目根目录执行
npm link

# 验证链接是否成功
npm ls -g --depth=0

2. 在 settings.json 中配置本地路径

Claude Code 通过项目级别的 .claude/settings.json 或全局 settings.json 来加载 Plugin。在其中添加 plugins 配置指向本地 Plugin 路径：

{
  "plugins": {
    "my-plugin": {
      "path": "C:/Users/YourName/projects/my-plugin"
    }
  }
}

配置完成后，重启 Claude Code 使配置生效。可以通过 /plugins 命令查看当前已加载的 Plugin 列表，确认你的 Plugin 是否被正确识别。

3. 测试 Plugin 命令是否正常注册

在 Claude Code 中使用以下方法测试 Plugin 是否正常工作：

输入 /plugins 命令查看已注册的 Plugin 列表
输入 /my-plugin hello 测试 hello 命令是否正常响应
查看 Claude Code 的输出日志确认无错误信息

4. 验证 Plugin 功能

编写单元测试来验证 Plugin 的核心功能。使用 Jest 或 Vitest 编写测试用例：

// tests/index.test.js
import { describe, it, expect } from '@jest/globals';
import plugin from '../src/index.js';

describe('My Plugin', () => {
  it('should register hello command', async () => {
    const result = await plugin.commands.helloCommand(
      { name: 'World' },
      {}
    );
    expect(result.type).toBe('text');
    expect(result.content).toContain('Hello');
  });
});

注意事项：本地加载测试时，确保 Plugin 目录路径中不包含中文或特殊字符，避免路径解析问题。如果 Plugin 没有正常加载，请检查 settings.json 的 JSON 格式是否正确，以及 path 字段指向的是否为 Plugin 的根目录（包含 manifest.json 的目录）。

五、调试和热重载

1. 设置调试端口

Claude Code Plugin 支持通过 Node.js 的 inspect 标志进行调试。在启动 Claude Code 时添加调试参数：

# 启动 Claude Code 并开启调试端口
claude --inspect=9229

# 在 Chrome 浏览器中打开 chrome://inspect
# 点击 "Open dedicated DevTools for Node" 进行调试

这样就可以在 Chrome DevTools 中设置断点、单步执行和检查变量，极大提升调试效率。

2. 使用 console.log 输出调试信息

在 Plugin 代码中可以使用 console.log 输出调试信息，这些信息会显示在 Claude Code 的日志中：

export default definePlugin({
  commands: {
    helloCommand: async (args, context) => {
      console.log('[my-plugin] helloCommand called with args:', args);
      console.log('[my-plugin] context:', JSON.stringify(context, null, 2));

      const result = {
        type: 'text',
        content: `Hello, ${args.name || 'World'}!`
      };

      console.log('[my-plugin] returning result:', result);
      return result;
    }
  }
});

建议在所有关键逻辑路径上都添加日志输出，并加上 Plugin 名前缀以便在日志中区分不同 Plugin 的输出。

3. 热重载配置（nodemon）

开发过程中频繁手动重启会降低效率。可以使用 nodemon 实现文件变更时的自动重载：

# 安装 nodemon
npm install --save-dev nodemon

# 在 package.json 中添加启动脚本
"scripts": {
  "dev": "nodemon --watch src --ext js,json --exec 'npm run build'",
  "build": "node scripts/build.js",
  "start": "node src/index.js"
}

配合 VS Code 的 tasks 功能，可以在保存文件时自动触发重载流程，实现近乎实时的开发反馈循环。

4. 常见开发错误排查

以下是 Plugin 开发中常见的错误及其解决方案：

Plugin 未加载：检查 manifest.json 格式是否正确，路径是否指向包含 manifest.json 的目录
命令未注册：确认 manifest.json 中的 commands 数组配置正确，handler 名称与代码中导出的函数名一致
依赖缺失错误：运行 npm install 重新安装所有依赖，检查 package.json 中的 dependencies 是否完整
路径解析错误：Windows 路径请使用正斜杠或双反斜杠，避免使用单反斜杠导致的转义问题
版本兼容性问题：检查 @anthropic-ai/claude-code-plugin 版本与 Claude Code 版本是否兼容

调试原则：从简到繁逐步排查。首先确认 Plugin 能被 Claude Code 识别（/plugins 命令），然后测试基本命令是否可调用，最后检查具体功能的逻辑正确性。每次修改后都重新加载 Plugin，避免使用缓存的结果进行调试。

六、版本控制和 CI 集成

1. .gitignore 配置建议

合理的 .gitignore 配置可以避免将不必要的文件提交到版本控制系统中：

# 依赖目录
node_modules/

# 构建输出
dist/
build/
out/

# 环境变量
.env
.env.local
.env.*.local

# IDE 配置
.vscode/settings.json
.idea/
*.swp
*.swo

# 操作系统文件
.DS_Store
Thumbs.db

# 日志文件
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# 测试覆盖率
coverage/

2. 自动化测试集成

在 CI 流程中集成自动化测试，确保 Plugin 质量和稳定性。以下是一个 GitHub Actions 配置示例：

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18.x, 20.x]

    steps:
    - uses: actions/checkout@v4
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
    - run: npm ci
    - run: npm run lint
    - run: npm test
    - run: npm run build

该配置会在每次推送和 PR 时自动运行 lint 检查、单元测试和构建，确保代码质量。建议在 package.json 中配置 lint 和 test 脚本，方便本地和 CI 环境统一调用。

3. 发布前检查清单

在发布 Plugin 到生产环境或公开仓库之前，请逐一检查以下项目：

所有占位符和测试数据已替换为真实内容
manifest.json 中的版本号已更新
package.json 中的 name、version、description 字段完整准确
所有依赖已声明在 package.json 的 dependencies 中（而非 devDependencies）
单元测试全部通过：npm test
代码规范检查通过：npm run lint
构建过程无错误：npm run build
README 文档已更新，包含安装说明和使用示例
.gitignore 已正确配置，敏感信息不会被提交
已在不同环境中进行集成测试，确认 Plugin 功能正常

最佳实践：建议在发布前先在本地环境中完成完整的端到端测试流程，模拟用户使用场景验证所有功能。版本号遵循 semver 语义化版本规范（主版本.次版本.补丁版本），确保版本号变更能够清晰传达变更的兼容性影响。