Claude文档(一) Claude Code 安装配置

概述

Claude Code 是 Anthropic 推出的终端驻留式 AI 编程代理工具, 能够完整理解代码库上下文, 通过自然语言指令完成代码阅读、生成、修改、git 操作等任务。

Claude Code 官网

核心特性

智能代码库理解: 使用 agent 搜索理解整个代码库结构, 无需手动选择上下文文件
多文件协作: 能够在多个文件间协调修改, 保持代码一致性
原生工具集成: 支持所有 CLI 工具, 包括 Git、包管理器、构建系统等
安全可控: 修改文件前始终请求权限, 不会意外破坏代码
多平台支持: 可在终端、VS Code、JetBrains IDEs 和浏览器中使用

适用场景

中大型项目的重构和特性开发
理解遗留代码和复杂业务逻辑
自动化测试生成和 bug 修复
跨文件代码迁移和架构调整
文档生成和代码审查

✅ 效率提升: 相比传统代码补全工具, Claude Code 更像一个可执行多步计划的”同事”, 能够将编码效率提升 2-4 倍。

安装配置

Claude Code 官方推荐使用原生二进制安装方式(npm 方式已标记 deprecated)。

系统要求

Node.js: 18.0 或更高版本
操作系统: macOS、Linux(含 WSL2)、Windows
网络: 需要访问 Anthropic API 或兼容服务

安装方法

方法一: Homebrew 安装(推荐)

# 确保 brew 已更新
brew update

# 安装 Claude Code(会自动拉取最新稳定版)
brew install --cask claude-code

💡 Homebrew 会自动配置 PATH 环境变量, 无需手动配置。

方法二: 官方安装脚本

1 2	# 下载并执行安装脚本(会放置在 /usr/local/bin/claude) curl -fsSL https://claude.ai/install.sh \| bash

⚠️ 如果使用 nvm 安装 Node.js, 可能会遇到权限问题, 建议使用 Homebrew 方式。

使用官方安装脚本(推荐)

# 下载并执行安装脚本(会放置在 ~/.local/bin/claude)
curl -fsSL https://claude.ai/install.sh | bash

# 添加到 PATH(如果尚未添加)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

使用 Node.js 全局安装(备用方案)

# 确保 Node.js >= 18
node --version

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

💡 npm 方式需要确保有全局 npm 权限, 避免使用 sudo。

推荐方案: WSL2 + Ubuntu

# 在 PowerShell 中安装 WSL2
wsl --install

# 安装完成后, 在 WSL Ubuntu 中按上述 Linux 方式安装

原生 Windows 支持(实验性)

1 2	# 使用 PowerShell 安装脚本 irm https://claude.ai/install.ps1 \| iex

⚠️ 原生 Windows 支持仍在完善中, 稳定性与生态完整度建议走 WSL。

验证安装

安装完成后验证:

1 2	claude --version # 应输出版本号, 如 v2.0.14

如果输出了版本号, 说明安装成功。

Claude Code 安装文档

https://docs.anthropic.com/en/docs/claude-code/overview

VS Code / JetBrains IDE 扩展

如果需要在 IDE 中使用 Claude Code:

💡 IDE 扩展提供可视化 diff 对比, 适合需要频繁查看代码变更的场景。

认证配置

Claude Code 支持三种主要认证模式:

创建多模型 alias

建议创建不同模型的 alias, 方便快速切换:

# ~/.bashrc 或 ~/.zshrc

# 官方 Claude(需要代理)
alias claude-claude="ANTHROPIC_BASE_URL=https://api.anthropic.com ANTHROPIC_API_KEY=sk-ant-... claude"

# 智谱 GLM-4.7
alias claude-glm="ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic/v1 ANTHROPIC_API_KEY=sk-xxx claude"

# z.ai GLM-4.7
alias claude-zai="ANTHROPIC_BASE_URL=https://api.z.ai/v1 ANTHROPIC_API_KEY=sk-xxx claude"

# 应用配置
source ~/.bashrc  # 或 source ~/.zshrc

使用示例:

# 使用官方 Claude
claude-claude

# 使用智谱 GLM-4.7
claude-glm

# 使用 z.ai GLM-4.7
claude-zai

模型选择与优化配置

Claude Code 模型映射

Claude Code 使用三种模型层级:

模型	用途	GLM-4.7 映射	特点
Haiku	轻量级任务	glm-4.5-air	快速响应, 适合简单查询
Sonnet	主要开发工作	glm-4.7	平衡性能与速度
Opus	复杂推理任务	glm-4.7	最强能力, 适合复杂架构设计

💡 GLM-4.7-long 上下文更稳定, 适合超过 100k token 的巨型代码库分析。

配置 GLM-4.7 模型映射

修改 ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.7"
  }
}

验证模型配置

启动 Claude Code 后, 使用 /status 命令查看当前模型状态:

1
2
3

claude
# 在 Claude Code 交互界面中
claude > /status

应显示类似:

1 2	Current Model: glm-4.7 Base URL: https://open.bigmodel.cn/api/anthropic/v1

快速开始

启动 Claude Code

进入任意项目目录, 直接启动:

1 2	cd ~/projects/my-app claude

出现 claude > 提示符即成功。

首次使用授权

首次启动时, Claude Code 会请求文件访问权限:

1 2	Claude Code wants to access files in /Users/xxx/projects/my-app [Allow] [Deny]

选择 Allow 以授予访问权限。

⚠️ 如果误选了 Deny, 可以在 ~/.claude/settings.json 中删除相关路径配置。

基础测试指令

使用 /ask 指令(不修改文件)

1	/ask 当前项目使用什么语言? package.json 和 requirements.txt 里主要依赖是什么?

使用自然语言指令

1	帮我分析 src/components 目录下所有组件的作用和关系

正常情况下 5–15 秒内会返回带文件树和关键代码引用的分析。

查看帮助信息

/help

会列出所有可用指令和快捷键。

核心功能使用

Slash Commands(必须掌握)

Claude Code 使用 / 开头的 slash command 与纯自然语言两种交互方式。

常用内置指令:

指令	作用	示例
`/ask`	提问(不修改文件)	`/ask 这个函数的性能瓶颈可能在哪里?`
`/generate`	生成新文件或代码片段	`/generate 创建一个用户登录的 RESTful 接口`
`/edit`	修改已有文件	`/edit 在 auth.js 中添加 JWT 刷新逻辑`
`/run`	执行 shell 命令(需确认)	`/run npm test`
`/git`	git 操作	`/git commit -m "feat: add login endpoint"`
`/model`	查看&切换当前模型	`/model list`
`/status`	查看当前状态	`/status`
`/clear`	清空对话历史	`/clear`
`/help`	完整指令列表	`/help`

💡 /ask 指令适合探索性提问, 不会修改任何文件。

典型使用场景

1. 快速理解陌生项目

1	给我一份这个仓库的架构概览, 重点标注入口文件和核心模块

Claude Code 会:

扫描项目结构
分析 package.json/requirements.txt
识别主要模块和依赖关系
生成架构概览

e.g.

claude > 给我一份这个仓库的架构概览, 重点标注入口文件和核心模块

# Claude Code 会分析并输出类似:
- 入口文件: src/index.ts
- 核心模块:
  - src/auth/: 认证模块
  - src/api/: API 路由
  - src/utils/: 工具函数
  - src/components/: React 组件

2. 批量生成测试用例

1	在 __tests__ 目录下为所有 utils/*.ts 文件生成 jest 测试用例, 覆盖率目标 90%

Claude Code 会:

读取所有 utils 文件
分析函数签名和逻辑
生成完整的测试用例
确保覆盖率达标

e.g.

claude > 在 __tests__ 目录下为所有 utils/*.ts 文件生成 jest 测试用例

# Claude Code 会:
1. 分析 src/utils/format.ts, src/utils/validate.ts 等
2. 生成 __tests__/format.test.ts, __tests__/validate.test.ts
3. 包含边界测试、错误处理测试

3. 跨文件重构

1	把所有 class 组件统一改写为 function component + hooks, 改动尽量原子化, 每个文件单独 commit

Claude Code 会:

找到所有 class 组件
逐个改写为 hooks
每改完一个文件提交一次
保持代码风格一致

e.g.

claude > 把所有 class 组件改写为 function component + hooks, 每个文件单独 commit

# Claude Code 会:
1. 搜索所有 class 组件
2. 逐个改写为 hooks
3. 运行 git commit 对每个文件单独提交

4. 自动修复 lint & type 错误

1	运行 tsc --noEmit 后把所有报错修复掉, 必要时添加类型声明

Claude Code 会:

运行 TypeScript 编译器
分析所有错误
自动修复或添加类型声明
验证修复结果

e.g.

claude > 运行 tsc --noEmit 后修复所有类型错误

# Claude Code 会:
1. 执行 tsc --noEmit
2. 分析错误列表
3. 逐个修复类型错误
4. 再次运行 tsc 验证

⚠️ GLM-4.7 在多轮工具调用连续性上稍逊官方 Sonnet 模型, 复杂任务建议在 prompt 里明确写 “step by step, don’t stop until finished”。

使用技巧

明确指令

❌ 模糊指令:

帮我优化一下代码

✅ 明确指令:

1	把 src/api/user.ts 中的所有 Promise 链改写为 async/await, 保持错误处理逻辑不变

分步执行

对于复杂任务, 分步执行效果更好:

# 第一步: 分析问题
/ask 这个项目中的类型错误主要集中在哪些文件?

# 第二步: 修复问题
修复 src/api/auth.ts 中的所有类型错误, 添加必要的类型声明

# 第三步: 验证结果
/run npm run type-check

交互式确认

Claude Code 在执行危险操作前会请求确认:

⚠️  Claude Code will delete the following files:
- src/old-component.tsx
- src/old-utils.ts

Continue? [y/N]

🚫 始终仔细查看变更内容, 特别是删除操作。

进阶功能

MCP 工具扩展

Claude Code 支持 MCP(Model Context Protocol)服务器扩展能力, 可以增强其功能:

常用 MCP 服务器

文件系统 MCP(深度文件操作)

1 2	# 添加文件系统 MCP(常用于大项目索引) claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .

浏览器自动化 MCP(让 Claude 自己查文档)

1 2	# 添加 Puppeteer MCP claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer

搜索增强 MCP

1 2	# 添加 Brave Search MCP claude mcp add brave-search -- npx -y @modelcontextprotocol/server-brave-search

GitHub MCP

1 2	# 添加 GitHub MCP(集成 GitHub API) claude mcp add github -- npx -y @modelcontextprotocol/server-github

💡 MCP 服务器需要额外的配置和认证, 参考 MCP 官方文档。

查看/移除 MCP

# 查看已安装的 MCP
claude mcp list

# 移除 MCP 服务器
claude mcp remove <mcp-name>

MCP 官方文档

https://docs.anthropic.com/en/docs/build-with-claude/mcp

自定义配置

配置文件位置

全局配置: ~/.claude/settings.json
项目配置: .claude/settings.json

常用配置项

{
  // 模型配置
  "env": {
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.7",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": 64000,
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
  },

  // 允许的工具
  "allowedTools": [
    "Read",
    "Write",
    "Edit",
    "Bash",
    "Git"
  ],

  // 禁用的工具
  "disabledTools": [],

  // 自动确认操作(谨慎使用)
  "dangerouslySkipPermissions": false,

  // 自定义系统提示
  "systemPrompt": "你是一个专业的全栈工程师..."
}

🚫 dangerouslySkipPermissions 会跳过所有权限确认, 仅在完全信任的环境中使用。

环境变量配置

除了在 ~/.claude/settings.json 中配置, 也可以使用环境变量:

# ~/.bashrc 或 ~/.zshrc

# API 配置
export ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic/v1
export ANTHROPIC_API_KEY=sk-xxx...

# 模型配置
export ANTHROPIC_DEFAULT_SONNET_MODEL=glm-4.7
export ANTHROPIC_DEFAULT_OPUS_MODEL=glm-4.7

# 性能配置
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# 代理配置(如需要)
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

💡 环境变量优先级高于 settings.json。

最佳实践

工作流程

1. 需求分析阶段

使用 /ask 探索问题:

1	/ask 这个项目的认证流程是如何实现的? 涉及哪些文件?

2. 方案设计阶段

让 Claude Code 提供多个方案:

1	给出三种重构数据库查询的方案, 对比优劣和实现难度

3. 实现阶段

使用明确的指令:

1	创建 src/utils/db.ts, 实现方案一中的数据库连接池, 使用 TypeORM

4. 测试阶段

自动生成测试:

1	为 src/utils/db.ts 生成完整的单元测试, 覆盖所有分支

5. 提交阶段

使用 /git 提交:

1 2	/git add . /git commit -m "feat: implement database connection pool"

提示词工程

好的提示词特征

具体明确: 指定文件名、函数名、具体行为
上下文完整: 提供必要的背景信息
约束清晰: 说明不能做什么
可验证: 有明确的验收标准

e.g. 好的提示词:

在 src/api/auth.ts 中添加 JWT token 刷新功能:
1. 使用 jsonwebtoken 库
2. 实现 refresh() 函数, 接收旧 token, 返回新 token
3. 添加过期时间检查, 过期返回 401
4. 保持现有的 login() 和 logout() 函数不变
5. 添加类型声明

不好的提示词特征

❌ 模糊:

优化一下认证代码

❌ 缺少上下文:

添加一个新功能

❌ 约束不清:

1	重构这个文件, 但不要改太多

团队协作

统一配置

在项目根目录创建 .claude/settings.json:

{
  "env": {
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7"
  },
  "systemPrompt": "这是团队 X 的项目, 遵循以下编码规范:..."
}

文档化使用规范

创建 CLAUDE.md 文件:

# Claude Code 使用规范

## 常用指令

## 项目结构

## 编码规范

## 测试要求

✅ 将 .claude/ 和 CLAUDE.md 加入版本控制。

性能优化

减少上下文加载

使用具体路径而非通配符:

❌ 不好:

分析所有组件文件

✅ 好:

1	分析 src/components/Auth/Login.tsx 和 src/components/Auth/Register.tsx

使用轻量模型

简单查询使用 Haiku:

1 2	/model haiku /ask 这个函数的作用是什么?

清理历史记录

定期清理对话历史:

/clear

⚠️ 长对话会占用大量 token, 影响响应速度。

安全建议

不要泄露敏感信息

❌ 危险:

1	这是一个生产环境的数据库配置, host=prod-db.example.com, user=admin, password=xxx, 帮我优化查询

✅ 安全:

1 2	优化以下数据库查询, 使用参数化查询防止 SQL 注入: [提供脱敏后的查询代码]

审查生成的代码

Claude Code 生成的代码需要:

安全审查(SQL 注入、XSS、CSRF 等)
性能测试(时间复杂度、资源使用)
边界测试(异常输入、并发场景)

🚫 不要直接在生产环境使用生成的代码。

权限管理

使用 allowedTools 限制可用工具:

{
  "allowedTools": [
    "Read",
    "Edit",
    "Grep"
  ],
  "disabledTools": [
    "Bash",
    "Git"
  ]
}

常见问题

安装问题

Q: brew 安装后找不到 claude 命令

检查 PATH 配置:

# 查看 PATH
echo $PATH

# 应包含 /opt/homebrew/bin (Apple Silicon) 或 /usr/local/bin (Intel)
# 如果没有, 添加到 ~/.zshrc
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Q: npm 安装后权限不足

不要使用 sudo, 使用 nvm 安装 Node.js:

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 使用 nvm 安装 Node.js
nvm install 18
nvm use 18

# 重新安装 Claude Code
npm install -g @anthropic-ai/claude-code

认证问题

Q: 提示 Invalid API key

检查环境变量:

# 查看 API Key
echo $ANTHROPIC_API_KEY

# 应该输出 sk- 开头的 key
# 如果为空, 检查配置文件
cat ~/.zshrc | grep ANTHROPIC

Q: 网络超时

配置代理或使用国内服务:

# 方案一: 配置代理
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# 方案二: 使用智谱 GLM-4.7
export ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic/v1
export ANTHROPIC_API_KEY=sk-xxx...

配置问题

Q: 修改 settings.json 后不生效

重启 Claude Code:

1
2
3

# 关闭所有 Claude Code 窗口
# 重新打开终端
claude

如果还不生效, 检查 JSON 格式:

1 2	# 验证 JSON 格式 cat ~/.claude/settings.json \| python -m json.tool

Q: 模型切换失败

检查模型名称:

# 查看当前模型
claude > /status

# 查看可用模型
claude > /model list

确保模型名称正确:

Haiku: glm-4.5-air
Sonnet: glm-4.7
Opus: glm-4.7

使用问题

Q: 响应速度慢

可能的原因和解决方案:

代码库太大: 使用具体路径而非通配符
输出 token 限制太小: 增加 CLAUDE_CODE_MAX_OUTPUT_TOKENS
网络慢: 配置代理或使用国内服务
模型太重: 切换到 Haiku 处理简单任务

Q: 生成的代码有错误

提供更详细的上下文:

# 不好
修复这个 bug

# 好
修复以下 bug: 当用户名包含中文时, 登录失败.
文件: src/api/auth.ts
函数: login()
错误信息: "Invalid username"
期望行为: 支持中文用户名

Q: 如何回滚 Claude Code 的修改

使用 Git:

# 查看变更
git diff

# 撤销未提交的修改
git checkout -- <file>

# 回滚已提交的修改
git revert <commit-hash>

P.S. Claude Code 的所有操作都会经过 Git, 可以随时回滚。

MCP 问题

Q: MCP 服务器无法连接

检查 MCP 配置:

# 查看 MCP 列表
claude mcp list

# 查看 MCP 日志
claude mcp logs <mcp-name>

常见问题:

端口被占用: 更换端口
认证失败: 检查 API Key
网络不通: 配置代理

参考资料

官方文档

Claude Code 官网

https://code.claude.com

Claude Code 开发者文档

https://docs.anthropic.com/en/docs/claude-code/overview

MCP 协议规范

https://docs.anthropic.com/en/docs/build-with-claude/mcp

Claude API 文档

https://docs.anthropic.com/en/api/index

社区资源

anthropics/claude-code

https://github.com/anthropics/claude-code

MCP 服务器列表

https://github.com/modelcontextprotocol

国内资源

智谱 GLM-4.7 接入指南

https://docs.z.ai/scenario-example/develop-tools/claude

智谱 AI 开放平台

https://open.bigmodel.cn

z.ai 文档

https://docs.z.ai

概述

核心特性

适用场景

安装配置

系统要求

安装方法

验证安装

VS Code / JetBrains IDE 扩展

认证配置

创建多模型 alias

模型选择与优化配置

Claude Code 模型映射

配置 GLM-4.7 模型映射

推荐配置组合

验证模型配置

快速开始

启动 Claude Code

首次使用授权

基础测试指令

查看帮助信息

核心功能使用

Slash Commands(必须掌握)

典型使用场景

1. 快速理解陌生项目

2. 批量生成测试用例

3. 跨文件重构

4. 自动修复 lint & type 错误

使用技巧

明确指令

分步执行

交互式确认

进阶功能

MCP 工具扩展

常用 MCP 服务器

查看/移除 MCP

自定义配置

配置文件位置

常用配置项

环境变量配置

最佳实践

工作流程

1. 需求分析阶段

2. 方案设计阶段

3. 实现阶段

4. 测试阶段

5. 提交阶段

提示词工程

好的提示词特征

不好的提示词特征

团队协作

统一配置

文档化使用规范

性能优化

减少上下文加载

使用轻量模型

清理历史记录

安全建议

不要泄露敏感信息

审查生成的代码

权限管理

常见问题

安装问题

认证问题

配置问题

使用问题

MCP 问题

参考资料

官方文档

社区资源

国内资源

相关工具