Claude Code 使用指南

本教程将指导您完成 Claude Code 的安装、模型配置、Skill 安装以及 MCP 配置，帮助您快速搭建 AI 编程助手环境。

1 npm 环境配置

1.1 安装 Node.js

访问 Node.js 官网下载并安装 LTS 版本，安装路径建议修改为 D:\Program Files\nodejs。

安装完成后，在 Node.js 安装目录下创建全局 npm 文件夹（用于存放全局模块和缓存）：

创建 Node 全局 npm 文件夹

1.2 配置环境变量

在系统环境变量中分别配置用户变量和系统变量：

用户变量（Path 中添加）：用户变量 Path 配置

系统变量（新建 NODE_PATH）：系统变量 NODE_PATH 配置

1.3 安装 Claude Code

bash

# 全局安装
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version
# 输出示例：claude 1.x.x

# 查看帮助
claude --help

安装失败？

如果上述命令安装失败，可尝试以下命令：

bash

npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmjs.org/ --include=optional --allow-scripts=@anthropic-ai/claude-code

2 ccswitch 配置

2.1 安装 ccswitch

ccswitch 是一款 Claude Code 的模型路由工具，支持将 Claude Code 连接到自定义模型端点。

访问 ccswitch 官网下载并安装。

2.2 模型配置

配置 ccswitch 自定义模型需要先开启路由功能。点击设置 → 开启路由功能：

ccswitch 开启路由功能

然后点击右上角 + 号新建模型配置，填入以下信息：

模型端点 和 API Key：可在 统一门户 → AI Hub → 能力中心 → 统一大模型网关 获取

模型端点与 API Key 配置

点击 获取模型，软件会自动从 LLM 端点拉取可用模型列表，选择所需模型后保存即可：

获取可用模型列表

3 Skill 安装

3.1 什么是 Skill

Skill 是 Claude Code 的结构化指令集，用于扩展 AI 编程助手的能力。每个 Skill 本质上是一个 Markdown 文件（SKILL.md），告诉 Claude Code 在特定场景下如何工作。

3.2 安装 Skill 的方式

方式一：通过 `/skill` 命令安装（推荐）

在 Claude Code 对话中直接输入：

bash

/skill install <skill-name>

例如安装官方安全审查 Skill：

bash

/skill install security-review

方式二：从 GitHub 仓库安装

bash

/skill install https://github.com/user/skill-repo

方式三：手动安装自定义 Skill

将 Skill 文件放置到 Claude Code 的 Skills 目录：

bash

# Windows
%USERPROFILE%\.claude\skills\

# macOS / Linux
~/.claude/skills/

3.3 自定义 Skill 示例

创建一个 my-skill/SKILL.md 文件：

markdown

# My Custom Skill

你是一个代码审查助手。当审查代码时，请遵循以下流程：

1. 检查代码风格是否符合团队规范
2. 识别潜在 bug 和性能问题
3. 给出具体的改进建议
4. 按优先级排序输出结果

安装后，在 Claude Code 中通过 /skill my-skill 即可激活。

3.4 常用 Skill 推荐

Skill	用途
`security-review`	安全漏洞审查
`frontend`	前端/UI 开发辅助
`debugging`	调试和问题排查
`git-master`	Git 操作辅助
`writing-plans`	开发计划生成

更多 Skill 可在 Agent Skills 官方市场浏览和下载。

4 Hooks 配置

4.1 什么是 Hooks

Hooks 是用户定义的 Shell 命令、HTTP 端点或 LLM 提示，在 Claude Code 生命周期的特定时间点自动执行。它们提供确定性的行为控制，确保某些操作总是发生，而不是依赖 LLM 自主决定是否执行。

Hooks vs Skills 的区别：

维度	Hooks	Skills
触发方式	事件驱动（自动执行）	命令驱动（手动调用）
确定性	✅ 确定性，总执行	❌ LLM 决定是否使用
适用场景	格式化代码、通知、权限检查	代码审查、调试、文档生成

4.2 Hook 生命周期

Hooks 在 Claude Code 会话的三个节奏中触发：

会话级别（一次）：
  SessionStart → ... → SessionEnd

轮次级别（每轮一次）：
  UserPromptSubmit → [Agentic Loop] → Stop / StopFailure

工具调用级别（每次工具调用）：
  PreToolUse → [工具执行] → PostToolUse / PostToolUseFailure

4.3 所有 Hook 事件

事件	触发时机	过滤器字段
`SessionStart`	会话启动或恢复时	启动方式（startup/resume）
`Setup`	一次性环境准备	—
`UserPromptSubmit`	用户提交提示后	—
`UserPromptExpansion`	斜杠命令展开时	命令名
`PreToolUse`	工具调用之前	工具名
`PostToolUse`	工具调用成功之后	工具名
`PostToolUseFailure`	工具调用失败之后	工具名
`PostToolBatch`	批量工具调用完成后	—
`PermissionRequest`	请求权限时	工具名
`PermissionDenied`	权限被拒绝时	工具名
`Stop`	Claude 完成响应时	—
`StopFailure`	API 错误导致轮次结束时	—
`Notification`	Claude Code 发送通知时	—
`SubagentStart`	子 Agent 启动时	Agent 类型名
`SubagentStop`	子 Agent 停止时	Agent 类型名
`TaskCreated`	任务创建时	—
`TaskCompleted`	任务完成时	—
`WorktreeCreate`	Git worktree 创建时	—
`ConfigChange`	配置变更时	配置来源
`FileChanged`	文件系统文件变更时	文件名
`SessionEnd`	会话结束时	结束原因（clear/logout）

4.4 Hook 类型

类型	说明	输入方式
`command`	Shell 命令	JSON 通过 stdin 传入
`prompt`	LLM 提示评估	通过 `$ARGUMENTS` 变量
`agent`	Claude Agent 评估	自动传入上下文
`mcp_tool`	MCP 工具调用	作为 MCP 工具参数
`http`	HTTP 端点（POST）	作为请求体

4.5 配置文件位置

bash

# 全局配置（所有项目生效）
~/.claude/settings.json

# 项目级配置（仅当前项目生效）
.claude/settings.json

4.6 配置格式

json

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolName|Pattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-shell-command"
          }
        ]
      }
    ]
  }
}

4.7 实用示例

自动格式化代码

每次 Claude 编辑或写入文件后，自动运行 Prettier 格式化：

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

桌面通知

当 Claude 需要你的注意时发送桌面通知：

macOS：

json

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Linux：

json

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

阻止危险命令

在 git 命令执行前进行策略检查：

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

基于 Prompt 的停止判断

使用 LLM 评估是否应该停止：

json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."
          }
        ]
      }
    ]
  }
}

4.8 Hook 输入输出

Hook 命令通过 stdin 接收 JSON 格式的事件上下文，支持通过 stdout 返回 JSON 影响行为：

json

{
  "stopReason": "显示给用户的消息（当 continue 为 false 时）"
}

退出码 0：继续执行
退出码 1：非阻塞错误，继续执行（WorktreeCreate 事件除外，非零退出码中止创建）
其他非零退出码：阻塞行为

4.9 调试 Hooks

Hook 执行详情（匹配的 hooks、退出码、stdout/stderr）会被写入调试日志文件。可通过以下方式查看：

bash

# 在 Claude Code 中启用调试
# 查看 ~/.claude/logs/ 下的日志文件

5 MCP 配置

5.1 什么是 MCP

MCP（Model Context Protocol） 是 Anthropic 推出的开放标准协议，允许 Claude Code 通过统一接口调用外部工具和服务（如数据库、API、文件系统等）。

5.2 配置 MCP Server

Claude Code 支持通过 .mcp.json 文件配置 MCP Server。在项目根目录创建配置文件：

json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "E:\\code\\my-project"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-token>"
      }
    }
  }
}

配置说明

command：MCP Server 的启动命令
args：启动参数
env：环境变量（如 API Key）

5.3 常见 MCP Server 推荐

MCP Server	用途	安装命令
Filesystem	文件系统读写操作	`npx @modelcontextprotocol/server-filesystem <path>`
GitHub	管理 Issues、PR、仓库	`npx @modelcontextprotocol/server-github`
Postgres	数据库查询	`npx @modelcontextprotocol/server-postgres`
Brave Search	网络搜索	`npx @modelcontextprotocol/server-brave-search`
Puppeteer	浏览器自动化	`npx @modelcontextprotocol/server-puppeteer`

更多 MCP Server 可在 MCP 官方市场查看。

5.4 验证 MCP 配置

配置完成后，启动 Claude Code 时会自动加载 MCP Server。在对话中可通过以下方式验证：

bash

# 查看已加载的 MCP 工具
/mcp

如果 MCP Server 未正常加载，请检查：

配置文件路径是否正确
命令和参数是否有误
环境变量（如 API Key）是否已正确设置

Claude Code 使用指南 ​

1 npm 环境配置 ​

1.1 安装 Node.js ​

1.2 配置环境变量 ​

1.3 安装 Claude Code ​

2 ccswitch 配置 ​

2.1 安装 ccswitch ​

2.2 模型配置 ​

3 Skill 安装 ​

3.1 什么是 Skill ​

3.2 安装 Skill 的方式 ​

方式一：通过 /skill 命令安装（推荐） ​

方式二：从 GitHub 仓库安装 ​

方式三：手动安装自定义 Skill ​

3.3 自定义 Skill 示例 ​

3.4 常用 Skill 推荐 ​

4 Hooks 配置 ​

4.1 什么是 Hooks ​

4.2 Hook 生命周期 ​

4.3 所有 Hook 事件 ​

4.4 Hook 类型 ​

4.5 配置文件位置 ​

4.6 配置格式 ​

4.7 实用示例 ​

自动格式化代码 ​

桌面通知 ​

阻止危险命令 ​

基于 Prompt 的停止判断 ​

4.8 Hook 输入输出 ​

4.9 调试 Hooks ​

5 MCP 配置 ​

5.1 什么是 MCP ​

5.2 配置 MCP Server ​

5.3 常见 MCP Server 推荐 ​

5.4 验证 MCP 配置 ​

Claude Code 使用指南

1 npm 环境配置

1.1 安装 Node.js

1.2 配置环境变量

1.3 安装 Claude Code

2 ccswitch 配置

2.1 安装 ccswitch

2.2 模型配置

3 Skill 安装

3.1 什么是 Skill

3.2 安装 Skill 的方式

方式一：通过 `/skill` 命令安装（推荐）

方式二：从 GitHub 仓库安装

方式三：手动安装自定义 Skill

3.3 自定义 Skill 示例

3.4 常用 Skill 推荐

4 Hooks 配置

4.1 什么是 Hooks

4.2 Hook 生命周期

4.3 所有 Hook 事件

4.4 Hook 类型

4.5 配置文件位置

4.6 配置格式

4.7 实用示例

自动格式化代码

桌面通知

阻止危险命令

基于 Prompt 的停止判断

4.8 Hook 输入输出

4.9 调试 Hooks

5 MCP 配置

5.1 什么是 MCP

5.2 配置 MCP Server

5.3 常见 MCP Server 推荐

5.4 验证 MCP 配置