21.1 插件开发环境搭建

21.1.1 系统要求#

基本要求#

软件依赖#

21.1.2 安装开发工具#

1. 安装 Node.js#

推荐使用 nvm 进行 Node.js 版本管理：

bash
复制
# 安装 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh |bashsource ~/.bashrc

# 安装并使用 Node.js 18nvm install18nvm use 18
# 验证安装node --version
npm --version

2. 安装 Python#

macOS

bash
复制
brew install python@3.10

Ubuntu/Debian

bash
复制
sudoapt update
sudoaptinstall python3.10 python3.10-venv python3-pip

Windows

从 Python 官方网站 下载安装程序。

bash
复制
# 验证安装python3 --version
pip3 --version

3. 安装 Git#

macOS

bash
复制
brew installgit

Ubuntu/Debian

bash
复制
sudoaptinstallgit

Windows

从 Git 官方网站 下载安装程序。

bash
复制
# 验证安装git --version

4. 安装 Claude Code CLI#

bash
复制
# 使用 npm 安装npminstall -g @anthropic-ai/claude-code

# 验证安装claude --version

21.1.3 安装插件开发工具#

1. 安装插件脚手架工具#

bash
复制
# 安装插件脚手架npminstall -g @claude-code/plugin-scaffold

# 验证安装claude-plugin-scaffold --version

2. 安装插件开发工具#

bash
复制
# 安装开发工具npminstall -g @claude-code/plugin-devtools

# 验证安装claude-plugin-devtools --version

3. 安装插件测试工具#

bash
复制
# 安装测试工具npminstall -g @claude-code/plugin-test

# 验证安装claude-plugin-test --version

21.1.4 创建开发环境#

1. 创建项目目录#

bash
复制
# 创建插件项目目录mkdir my-plugin
cd my-plugin

# 初始化项目npm init -y

2. 安装开发依赖#

bash
复制
# 安装插件 SDKnpminstall @claude-code/plugin-sdk --save-dev

# 安装 TypeScript（推荐）npminstall typescript @types/node --save-dev

# 安装测试框架npminstall jest @types/jest --save-dev

# 安装代码检查工具npminstall eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin --save-dev

3. 配置 TypeScript#

json
复制
// tsconfig.json

4. 配置 ESLint#

json
复制
// .eslintrc.json

5. 配置 Jest#

json
复制
// jest.config.json

6. 配置 package.json#

json
复制
{

21.1.5 创建插件项目结构#

标准项目结构#

bash
复制
my-plugin/
├── src/
│   ├── index.ts              # 插件入口
│   ├── plugin.ts            # 插件主类
│   ├── tools/               # 工具定义
│   │   ├── tool1.ts
│   │   └── tool2.ts
│   ├── commands/            # 命令定义
│   │   ├── command1.ts
│   │   └── command2.ts
│   ├── utils/               # 工具函数
│   │   └── helpers.ts
│   └── types/               # 类型定义
│       └── index.ts
├── __tests__/               # 测试文件
│   ├── plugin.test.ts
│   ├── tools/
│   │   └── tool1.test.ts
│   └── commands/
│       └── command1.test.ts
├── dist/                    # 编译输出
├── templates/               # 模板文件
├── docs/                    # 文档
├── examples/                # 示例
├── .eslintrc.json          # ESLint 配置
├── .gitignore              # Git 忽略文件
├── jest.config.json        # Jest 配置
├── package.json            # 项目配置
├── plugin.yaml             # 插件清单
├── tsconfig.json           # TypeScript 配置
└── README.md               # 项目说明

创建目录结构#

bash
复制
# 创建目录结构mkdir -p src/tools src/commands src/utils src/types __tests__/tools __tests__/commands dist templates docs examples

# 创建基本文件touch src/index.ts src/plugin.ts src/types/index.ts
touch .eslintrc.json jest.config.json tsconfig.json plugin.yaml README.md
touch .gitignore

配置 .gitignore#

gitignore
复制
# Dependencies
node_modules/

# Build output
dist/

# Test coverage
coverage/

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

# Logs
*.log
npm-debug.log*

# Environment
.env
.env.local

# Temporary files
*.tmp
.cache/

21.1.6 配置开发环境#

1. 配置 IDE#

VS Code 配置

json
复制
// .vscode/settings.json
{
"typescript.tsdk": "node_modules/typescript/lib",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true
},
"files.exclude": {
"**/node_modules": true,
"**/dist": true,
"**/coverage": true
}
}

VS Code 扩展推荐

json
复制
// .vscode/extensions.json
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "ms-vscode.vscode-typescript-next"
  ]
}

VS Code 任务

json
复制
// .vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "npm",
      "script": "build",
      "problemMatcher": "$tsc",
      "group": {
        "kind": "build",
        "isDefault": true
      }
    },
    {
      "type": "npm",
      "script": "test",
      "problemMatcher": "$tsc",
      "group": {
        "kind": "test",
        "isDefault": true
      }
    },
    {
      "type": "npm",
      "script": "lint",
      "problemMatcher": "$eslint-stylish",
      "group": "build"
    }
  ]
}

2. 配置调试#

json
复制
// .vscode/launch.json

3. 配置 Git Hooks#

bash
复制
# 安装 huskynpminstall husky --save-dev

# 初始化 huskynpx husky install
# 添加 pre-commit hooknpx husky add .husky/pre-commit "npm run lint && npm run test"

21.1.7 创建插件清单#

plugin.yaml 配置#

yaml
复制
# plugin.yaml
name: my-plugin
version: 1.0.0
description: My Claude Code Plugin
author: Your Name
license: MIT
homepage: https://github.com/yourname/my-plugin
repository: https://github.com/yourname/my-plugin

# 插件入口
main: dist/index.js
types: dist/index.d.ts

# 插件权限
permissions:
  file:
    - read: "/"
  network:
    - https: ["api.example.com"]

# 插件依赖
dependencies:
  claude-code: ">=1.0.0"

# 开发依赖
devDependencies:
  typescript: "^4.9.0"
  jest: "^29.0.0"

# 插件配置
config:
  timeout: 30
  retries: 3

# 插件元数据
metadata:
  category: development
  tags:
    - code-generation
    - productivity
  keywords:
    - plugin
    - claude-code

21.1.8 验证开发环境#

1. 创建测试文件#

typescript
复制
// src/index.tsexport*from'./plugin';

typescript
复制
// src/plugin.tsimport{ Plugin }from'@claude-code/plugin-sdk';
exportclassMyPluginextendsPlugin{constructor(){super({      name:'my-plugin',      version:'1.0.0',      description:'My Claude Code Plugin'});}
asyncinitialize():Promisevoid>{console.log('Plugin initialized');}
asyncstart():Promisevoid>{console.log('Plugin started');}
asyncstop():Promisevoid>{console.log('Plugin stopped');}}

2. 编译项目#

bash
复制
# 编译 TypeScriptnpm run build

# 检查编译输出ls -la dist/

3. 运行测试#

bash
复制
# 运行测试npmtest
# 运行测试并生成覆盖率报告npm run test -- --coverage

4. 运行代码检查#

bash
复制
# 运行 ESLintnpm run lint

# 自动修复问题npm run lint:fix

21.1.9 开发工作流#

1. 开发流程#

bash
复制
# 1. 创建功能分支git checkout -b feature/new-feature

# 2. 开发功能# 编辑代码...
# 3. 运行测试npmtest
# 4. 运行代码检查npm run lint

# 5. 编译项目npm run build

# 6. 提交更改gitadd.git commit -m "Add new feature"
# 7. 推送到远程git push origin feature/new-feature

# 8. 创建 Pull Request

2. 调试流程#

bash
复制
# 1. 启动开发模式npm run dev
# 2. 在 VS Code 中设置断点# 3. 按 F5 启动调试# 4. 在调试控制台中查看输出

3. 测试流程#

bash
复制
# 1. 编写测试# 创建测试文件...
# 2. 运行测试npmtest
# 3. 查看测试覆盖率npm run test -- --coverage

# 4. 运行特定测试npmtest -- --testNamePattern="MyPlugin"

21.1.10 常见问题解决#

1. TypeScript 编译错误#

bash
复制
# 清理编译缓存npm run clean
npm run build

# 重新安装依赖rm -rf node_modules package-lock.json
npminstall

2. 测试失败#

bash
复制
# 更新 Jest 配置npminstall --save-dev jest@latest ts-jest@latest

# 清理 Jest 缓存npmtest -- --clearCache

3. ESLint 错误#

bash
复制
# 自动修复 ESLint 错误npm run lint:fix

# 更新 ESLint 配置npminstall --save-dev @typescript-eslint/parser@latest @typescript-eslint/eslint-plugin@latest

4. 插件无法加载#

bash
复制
# 检查插件清单cat plugin.yaml

# 验证编译输出ls -la dist/

# 重新编译npm run clean
npm run build