Claude Code 安装与使用大全

Claude Code 是 Anthropic 公司推出的命令行 AI 编程助手，它能够理解代码库上下文、自动执行开发任务、通过自然语言指令帮助开发者更高效地编写代码。与传统的代码补全工具不同，Claude Code 是一个真正的代理式编程助手，可以自主规划、执行复杂的多步骤任务，包括代码编写、重构、调试、Git 操作等。本指南将从零开始，详细介绍 Claude Code 的安装配置、基础使用、进阶技巧以及最佳实践，帮助开发者充分发挥这一强大工具的潜力。

一、系统要求与前置条件

在安装 Claude Code 之前，需要确保系统满足以下要求。Claude Code 作为基于 Node.js 的命令行工具，对运行环境有一定的依赖，了解这些前置条件可以帮助避免安装过程中的常见问题。

1.1 操作系统支持

Claude Code 支持三大主流操作系统平台。macOS 用户需要版本 10.15 或更高版本；Linux 用户推荐使用 Ubuntu 20.04 及以上版本或 Debian 10 及以上版本；Windows 用户可以在 Windows 10 或 Windows 11 上直接使用，也可以在 WSL（Windows Subsystem for Linux）环境中运行。值得注意的是，Windows 原生支持和 WSL 环境下的安装方式略有不同，本指南将分别介绍。

对于 Windows 用户而言，推荐通过 WSL2 安装 Ubuntu 来获得最佳体验，因为这样可以避免许多 Windows 特有的路径和权限问题。WSL2 提供了完整的 Linux 内核支持，能够让 Claude Code 的所有功能都正常运行。如果选择直接在 Windows 上使用，需要注意路径格式（使用反斜杠）可能带来的兼容性问题，但大多数功能仍然可以正常使用。

1.2 硬件要求

硬件方面的要求相对宽松，但为了获得流畅的使用体验，建议满足以下条件。内存方面，最低要求 4GB，但推荐 8GB 或更高，因为 Claude Code 在处理大型代码库时需要加载和分析大量上下文信息。存储空间需要至少几百兆字节用于安装和缓存，实际使用中还需要考虑项目代码库的存储需求。网络方面，需要稳定的互联网连接来完成身份验证和 AI 模型交互，首次使用时需要通过 OAuth 进行一次性认证绑定账户。

1.3 软件依赖

Node.js 是 Claude Code 的核心依赖，必须安装 18.0 或更高版本，推荐使用 LTS（长期支持）版本 20.x 或 22.x。可以通过访问 Node.js 官网下载安装包，也可以使用 nvm（Node Version Manager）来管理多个 Node.js 版本。使用 nvm 的好处是可以在不同项目之间灵活切换 Node.js 版本，避免版本冲突问题。安装完成后，可以通过在终端执行 node -v 和 npm -v 命令来验证安装是否成功。

Git 虽然不是必需但强烈推荐安装，版本要求 2.23 或更高。Claude Code 会利用 Git 来读取项目历史、生成代码差异（diff）、创建 Pull Request 等。安装了 Git 后，Claude Code 能够更好地理解项目的版本控制状态，提供更精准的代码建议。如果需要在 Claude Code 内直接创建 Git 提交或处理 Pull Request，Git 是必不可少的。

此外，一些可选工具可以增强 Claude Code 的功能。ripgrep（rg）可以增强文件搜索能力；GitHub CLI 或 GitLab CLI 可以用于创建和管理 Pull Request 的工作流；Docker 可以用于需要容器化环境的开发任务。这些工具都是可选的，不影响 Claude Code 的核心功能，但安装后可以让相关功能更加完善。

二、安装指南

Claude Code 提供了多种安装方式，包括官方脚本安装、通过包管理器安装以及 NPM 全局安装。本节将详细介绍各平台的安装步骤，帮助用户选择最适合自己环境的安装方法。

2.1 官方一键安装脚本（推荐）

官方提供了一键安装脚本，这是最简单且推荐的方式，安装脚本会自动检测系统环境并完成安装，同时支持自动后台更新。

macOS、Linux、WSL 环境安装命令：

curl -fsSL https://claude.ai/install.sh | bash

这条命令会下载安装脚本并通过管道执行。安装过程中可能需要输入管理员密码来完成系统级安装。安装完成后，可以通过执行 claude --version 命令来验证是否安装成功。

Windows PowerShell 安装命令：

irm https://claude.ai/install.ps1 | iex

Windows PowerShell 用户可以直接使用这条命令完成安装。安装过程会自动处理 PATH 环境变量的配置，安装完成后即可直接使用。

Windows CMD 安装命令：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

如果习惯使用 CMD 命令行，可以先下载安装脚本，运行后再删除临时文件。

2.2 通过包管理器安装

对于已经使用包管理器的用户，也可以通过相应的包管理器来安装 Claude Code。

使用 Homebrew 安装（macOS）：

brew install --cask claude

Homebrew 是 macOS 上最流行的包管理器之一，通过 cask 安装桌面应用程序的方式安装 Claude Code。

使用 Winget 安装（Windows）：

winget install Anthropic.Claude

Windows Package Manager（winget）是 Windows 10 1709 及更高版本内置的包管理器，使用这条命令可以快速安装 Claude Code。

使用 APT 安装（Debian/Ubuntu）：

sudo apt update && sudo apt install claude

对于基于 Debian 和 Ubuntu 的 Linux 发行版，可以通过官方 APT 仓库安装。

2.3 NPM 全局安装

如果已经熟悉 Node.js 环境，也可以通过 npm 进行全局安装。这种方式适合需要使用特定版本或者对 npm 比较熟悉的开发者。

标准安装命令：

npm install -g @anthropic-ai/claude-code

执行这条命令后，Claude Code 会被安装到 Node.js 的全局模块目录中。安装完成后，通过 claude --version 确认安装成功。

国内用户使用镜像源：

由于网络原因，国内用户可能需要配置镜像源来加速安装：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

使用阿里云的 NPM 镜像源可以显著提高下载速度，避免安装过程中的网络超时问题。

2.4 验证安装

无论使用哪种安装方式，安装完成后都建议执行以下命令来验证安装结果：

claude --version

如果正确输出版本号信息（类似 Claude Code version x.x.x），说明安装成功。还可以执行：

claude --help

这会显示 Claude Code 的帮助信息，列出所有可用的命令和选项，帮助用户快速了解基本用法。

三、完整命令参考大全

本节整理了 Claude Code 所有可用的命令，包括命令行选项、斜杠命令、快捷键和配置文件命令，方便用户快速查阅。

3.1 命令行基础命令

3.1.1 启动与基本命令

命令	功能描述	使用示例
claude	启动交互式对话模式，进入 Claude Code 主界面	claude
claude "任务描述"	直接执行一次性任务，执行完成后自动退出	claude "修复构建错误"
claude -p "查询内容"	执行单次查询并立即退出，适合脚本集成	claude -p "解释这个函数"
claude -c "查询内容"	继续之前的对话会话，从中断处恢复	claude -c "继续实现剩余功能"
claude -r "session_id" "查询"	按会话 ID 恢复指定会话	claude -r "abc123" "继续工作"
claude --version	显示 Claude Code 版本信息	claude --version
claude --help	显示帮助信息和所有命令选项	claude --help
claude update	检查并更新到最新版本	claude update
claude mcp	启动 MCP（Model Context Protocol）向导	claude mcp

3.1.2 高级命令行选项

选项	功能描述	使用示例
--output-format json	以 JSON 格式输出结果，包含元数据	claude -p "生成函数" --output-format json
--output-format stream-json	流式输出 JSON 格式，实时显示结果	claude -p "构建组件" --output-format stream-json
--model <model-name>	指定使用的模型（opus、sonnet 等）	claude --model opus
--add-dir <path>	添加额外的工作目录到会话	claude --add-dir /path/to/lib
--no-config	跳过加载配置文件	claude --no-config
--verbose	显示详细调试信息	claude --verbose
--dry-run	预览操作但不实际执行	claude -p "修改文件" --dry-run

3.1.3 管道模式用法

Claude Code 支持通过管道接收输入，这在处理日志、文件流等场景下非常有用：

# 监控日志并实时分析
tail -f app.log | claude -p "发现异常时通知我"

# 处理文件内容
cat error.log | claude -p "分析这个错误日志"

# CI/CD 场景
git diff | claude -p "翻译新文本字符串并创建 PR"

3.2 斜杠命令（Slash Commands）

斜杠命令是 Claude Code 交互模式中的核心功能，以 / 开头用于执行特定操作。

3.2.1 会话管理命令

命令	功能描述	使用示例
/exit 或 /quit	退出当前对话会话	/exit
/new	开始全新的对话会话，清除所有上下文	/new
/continue	继续之前的对话（从最近中断处恢复）	/continue
/session	列出所有历史会话	/session
/session <name>	切换到指定名称的会话	/session "优化任务"
/session <id>	按会话 ID 切换会话	/session abc123
/clear	清除当前会话的对话历史但保持会话	/clear

3.2.2 项目配置命令

命令	功能描述	使用示例
/init	初始化项目文档，自动扫描项目结构	/init
/edit	编辑项目的 CLAUDE.md 记忆文件	/edit
/model	显示当前使用的模型	/model
/model opus	切换到 Opus 模型	/model opus
/model sonnet	切换到 Sonnet 模型	/model sonnet
/model haiku	切换到 Haiku 轻量模型	/model haiku

3.2.3 输出与上下文管理

命令	功能描述	使用示例
/compact	压缩当前对话上下文，保留关键信息减少 token 消耗	/compact
/tee <filename>	将输出同时保存到指定文件	/tee output.md
/help	显示所有可用的斜杠命令列表	/help
/think	开启深度思考模式，让 Claude 详细分析问题	/think
/thorough	启用全面模式，进行更深入的分析	/thorough
/resume	恢复对话到之前的状态	/resume

3.2.4 工具与权限管理

命令	功能描述	使用示例
/mcp	管理 MCP（Model Context Protocol）工具	/mcp list
/mcp add <name>	添加 MCP 工具	/mcp add filesystem
/mcp remove <name>	移除 MCP 工具	/mcp remove filesystem
/allow	允许当前操作的所有子操作	/allow
/allow bash	允许执行 bash 命令	/allow bash
/allow edit	允许编辑文件	/allow edit
/deny	拒绝当前操作	/deny
/deny bash	禁止执行 bash 命令	/deny bash

3.2.5 Git 与版本控制

命令	功能描述	使用示例
/git	显示当前 Git 状态	/git
/git commit	创建 Git 提交	/git commit "修复登录 bug"
/git branch	列出所有分支	/git branch
/git checkout <branch>	切换分支	/git checkout feature/login
/pr	创建 Pull Request	/pr
/merge	合并分支	/merge main

3.2.6 代码操作命令

命令	功能描述	使用示例
/test	运行测试套件	/test
/lint	运行代码检查	/lint
/lint --fix	运行代码检查并自动修复	/lint --fix
/build	执行构建命令	/build
/run	运行应用程序	/run
/install	安装依赖	/install

3.3 快捷键与键位绑定

3.3.1 交互模式快捷键

快捷键	功能描述	说明
Ctrl+C	中断当前操作	与 /exit 效果相同
Esc	中断模型生成	快速停止当前响应
Ctrl+D	发送多行输入结束	用于输入多行代码或文本
↑/↓	浏览输入历史	快速重复之前的命令
Ctrl+R	反向搜索历史命令	类似 bash 的反向搜索
Tab	自动补全命令	补全斜杠命令和文件名

3.3.2 VS Code 扩展快捷键

快捷键	功能描述	说明
⌘K 或 Ctrl+K	询问 AI	在 VS Code 中选中文本后按此快捷键
⌘I 或 Ctrl+I	生成代码	触发 AI 代码生成
右键菜单 > Ask Claude	右键上下文菜单	对选中文本执行 AI 操作
Ctrl+Shift+P > Claude Code	命令面板访问	通过命令面板调用功能

3.3.3 多行输入模式

当需要输入多行内容时，可以使用以下方式：

请输入多行文本，完成后按 Ctrl+D（Linux/macOS）或 Ctrl+Z（Windows）结束：

3.4 环境变量配置

3.4.1 认证与 API 配置

环境变量	功能描述	示例
ANTHROPIC_API_KEY	Anthropic API 密钥	export ANTHROPIC_API_KEY="sk-..."
ANTHROPIC_BASE_URL	API 服务器地址（自定义服务时使用）	export ANTHROPIC_BASE_URL="https://api.example.com"
ANTHROPIC_CLIENT_TIMEOUT	请求超时时间（毫秒）	export ANTHROPIC_CLIENT_TIMEOUT=60000

3.4.2 行为控制配置

环境变量	功能描述	示例
CLAUDE_ALLOW_BASH	允许执行 bash 命令	export CLAUDE_ALLOW_BASH=true
CLAUDE_ALLOW_DELETE	允许删除文件	export CLAUDE_ALLOW_DELETE=false
CLAUDE_ALLOW_EDIT	允许编辑文件	export CLAUDE_ALLOW_EDIT=true
CLAUDE_DISABLE_AUTO_UPDATE	禁用自动更新	export CLAUDE_DISABLE_AUTO_UPDATE=true

3.4.3 日志与调试配置

环境变量	功能描述	示例
CLAUDE_LOG_LEVEL	日志级别（debug、info、warn、error）	export CLAUDE_LOG_LEVEL=debug
DEBUG	启用调试模式	export DEBUG=claude:*

3.5 配置文件说明

3.5.1 配置文件位置

Claude Code 使用以下配置文件（按优先级排序）：

项目级：./claude.json
用户级：~/.claude.json
环境变量覆盖

3.5.2 CLAUDE.md 项目记忆文件

CLAUDE.md 是 Claude Code 的核心项目配置文件，放置在项目根目录：

标准 CLAUDE.md 结构：

# 项目名称

简要描述项目用途和技术栈。

## 开发环境

- Node.js 20+
- Python 3.11+
- PostgreSQL 15

## 代码规范

- 语言规范
- 代码风格指南
- 命名约定

## 测试要求

- 测试覆盖率要求
- 测试工具和框架

## Git 工作流

- 分支命名规范
- 提交信息格式
-PR 流程

## 常用命令

- 安装依赖
- 运行测试
- 启动开发服务器

## 注意事项

- 敏感信息处理
- 特定配置说明
- 已知问题

3.5.3 .claudeignore 排除文件

使用 .claudeignore 文件排除不需要扫描的目录和文件：

# 依赖目录
node_modules/
venv/
__pycache__/

# 构建输出
dist/
build/
*.log

# 敏感文件
.env
*.pem
*.key

# 测试覆盖率
coverage/
.nyc_output/

# IDE 配置
.idea/
.vscode/
*.swp

3.5.4 claude.json 配置文件示例

{
  "model": "sonnet",
  "temperature": 0.7,
  "maxTokens": 4096,
  "commands": {
    "test": "npm test -- --coverage",
    "lint": "npm run lint",
    "build": "npm run build",
    "dev": "npm run dev"
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  },
  "theme": "dark",
  "autoCompact": true,
  "compactThreshold": 15000
}

3.6 权限控制命令

Claude Code 提供了细粒度的权限控制机制：

3.6.1 会话级权限

权限	默认状态	说明
Read	始终允许	读取文件和代码库
Edit	首次询问	编辑和创建文件
Bash	首次询问	执行 Shell 命令
Web Fetch	首次询问	从网络获取信息
MCP Tools	首次询问	使用 MCP 协议工具

3.6.2 永久权限设置

/allow          # 允许当前会话的所有操作
/allow bash     # 永久允许执行 bash 命令
/allow edit     # 永久允许编辑文件
/allow web      # 永久允许网络访问
/deny           # 拒绝当前操作
/deny bash      # 永久禁止 bash 命令

3.7 MCP（Model Context Protocol）命令

MCP 允许扩展 Claude Code 的功能：

命令	功能描述	使用示例
/mcp	列出所有已安装的 MCP 工具	/mcp
/mcp add <name>	安装 MCP 工具	/mcp add filesystem
/mcp remove <name>	卸载 MCP 工具	/mcp remove filesystem
/mcp serve	启动 MCP 服务	/mcp serve

3.8 常用交互示例

3.8.1 日常开发场景

# 进入项目并开始工作
cd my-project
claude

# 在会话中可以使用
/init          # 初始化项目信息
/model sonnet  # 切换到轻量模型
/test          # 运行测试

3.8.2 快速查询

# 非交互式查询
claude -p "解释 src/utils/helper.ts 中的 parseConfig 函数"
claude -p "这个项目的技术栈是什么"

3.8.3 恢复工作

# 继续之前的会话
claude -c "继续实现用户认证模块"

3.8.4 脚本集成

# 使用 JSON 格式输出便于解析
claude -p "生成一个 hello world 函数" --output-format json

# 管道处理
git diff | claude -p "审查这些代码变更"

四、账户配置与身份验证

安装完成后，需要完成身份验证才能开始使用 Claude Code。Claude Code 支持多种身份验证方式，包括官方账户登录和 API 密钥配置。

3.1 官方账户登录

最简单的方式是通过 Anthropic 官方账户登录。首次运行 claude 命令时，系统会自动引导你完成登录流程。

首次启动：

cd your-project-directory
claude

执行 claude 命令后，如果尚未登录，系统会显示登录提示。用户需要访问 console.anthropic.com 使用 Anthropic 账户（Claude.ai 账户或 Claude Pro/Max 订阅账户）完成 OAuth 认证。认证过程是安全的一次性操作，完成后凭证会保存在本地，后续使用无需重新登录。

3.2 API 密钥配置

对于需要使用自定义 API 服务的场景，可以通过配置环境变量来使用第三方 API 服务。这种方式适合已经购买 API 额度或者使用自建 API 服务的开发者。

设置 API 密钥环境变量：

Linux/macOS：

export ANTHROPIC_API_KEY="your-api-key-here"
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

这条命令首先设置当前会话的环境变量，然后将配置写入 bashrc 文件使其永久生效，最后重新加载配置文件使改动立即生效。

Windows CMD：

setx ANTHROPIC_API_KEY "your-api-key-here"

Windows 用户可以使用 setx 命令将 API 密钥保存到系统环境变量中。

Windows PowerShell：

$env:ANTHROPIC_API_KEY="your-api-key-here"
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "your-api-key-here", "User")

PowerShell 用户可以使用 $env 设置当前会话变量，并使用 [Environment]::SetEnvironmentVariable 使其永久保存。

3.3 自定义 API 地址配置

如果使用的是第三方 API 服务，可能还需要配置自定义的 API 地址。

设置自定义 API 地址：

Linux/macOS：

export ANTHROPIC_BASE_URL="https://api.example.com"
echo 'export ANTHROPIC_BASE_URL="https://api.example.com"' >> ~/.bashrc
source ~/.bashrc

Windows：

setx ANTHROPIC_BASE_URL "https://api.example.com"

配置完成后，重新启动终端或执行 source ~/.bashrc（Linux/macOS）使配置生效。

3.4 多账户配置

对于需要在多个账户之间切换的场景，可以使用不同的环境变量配置来管理。一种常见做法是创建多个配置文件，然后根据需要 source 相应的配置文件：

# 创建账户配置
echo 'export ANTHROPIC_API_KEY="key1"' > ~/.claude/account1.env
echo 'export ANTHROPIC_API_KEY="key2"' > ~/.claude/account2.env

# 切换账户
source ~/.claude/account1.env  # 使用账户1
source ~/.claude/account2.env  # 使用账户2

这种方案允许用户在不同账户之间快速切换，方便管理个人和工作的不同项目。

四、基础使用方法

掌握 Claude Code 的基础使用方法是高效使用这一工具的前提。本节将介绍启动方式、交互模式、基本命令以及文件操作等核心功能。

4.1 启动与退出

启动交互式会话：

claude

直接输入 claude 命令进入交互模式，这是最常用的使用方式。进入后可以输入自然语言指令与 Claude Code 进行对话。

非交互式单次查询：

claude -p "Your question here"

使用 -p 参数可以直接在命令行中提问，无需进入交互模式。这适合快速获取答案或执行简单任务的场景。

查看帮助信息：

claude --help

显示所有可用的命令选项和使用说明，是学习工具功能的好帮手。

退出对话：

在交互模式中，可以输入 /exit 或按 Ctrl+C 组合键退出当前会话。

4.2 交互模式基础操作

进入交互模式后，用户可以通过自然语言与 Claude Code 进行交流。以下是一些常用的交互方式：

描述需求：

请帮我创建一个用户登录功能，包括用户名密码验证和会话管理。

寻求代码解释：

请解释这段代码的作用，特别是这个循环在做什么。

请求代码审查：

请帮我审查这段代码，看看有没有潜在的 bug 或性能问题。

寻求最佳实践建议：

在 Python 中处理大型文件时，什么是最佳实践？

在交互过程中，Claude Code 会根据上下文理解用户意图，并提供相应的帮助。需要注意的是，每次对话都会消耗 API 调用配额，对于使用按量付费账户的用户需要注意成本控制。

4.3 核心命令

Claude Code 提供了一系列以斜杠 / 开头的核心命令，用于执行特定操作。

会话管理命令：

命令	功能描述
/exit 或 /quit	退出当前会话
/new	开始一个新的对话会话
/continue	继续之前的对话（从中断处恢复）
/session	列出所有会话或切换会话

项目相关命令：

命令	功能描述
/init	初始化项目文档
/model	切换使用的模型
/edit	编辑项目记忆文件（CLAUDE.md）

输出控制命令：

命令	功能描述
/compact	压缩当前对话上下文，减少 token 消耗
/tee	将输出同时保存到文件

4.4 文件操作

Claude Code 可以直接读取、创建和修改项目文件，这是其作为代理式编程助手的核心能力之一。

读取文件：

请读取 src/utils/helper.js 文件，帮我理解这个工具函数的作用。

Claude Code 会自动读取指定文件并分析其内容，用户无需手动复制粘贴代码。

创建新文件：

请帮我创建一个新的 React 组件，用于显示用户信息卡片。

Claude Code 会根据上下文和最佳实践创建合适的文件结构。

修改现有文件：

请帮我重构这个函数，使其支持异步操作。

Claude Code 会分析现有代码，提供优化建议并进行修改。

批量操作：

请将项目中所有使用 var 声明的地方改为使用 let 或 const。

Claude Code 可以跨多个文件执行批量修改，提高重构效率。

4.5 代码执行与测试

Claude Code 可以在终端中执行命令，这对于运行测试、安装依赖、启动开发服务器等操作非常有用。

运行测试：

请运行项目中的单元测试，检查新增功能是否通过测试。

安装依赖：

请安装项目所需的 npm 依赖包。

启动开发服务器：

请启动开发服务器，让我可以在浏览器中预览效果。

执行 lint 检查：

请运行 ESLint 检查代码风格问题。

在执行这些命令时，Claude Code 会显示命令输出，如果遇到错误，会提供相应的解决方案。需要注意的是，某些危险操作（如删除文件、修改系统配置）需要用户明确授权才能执行。

五、进阶功能与高级技巧

掌握基础操作后，可以通过学习进阶功能来充分发挥 Claude Code 的潜力。本节将介绍 CLAUDE.md 配置、多模型选择、权限管理以及自动化任务等高级功能。

5.1 CLAUDE.md 项目配置

CLAUDE.md 是一个特殊的配置文件，Claude Code 在开始新对话时会自动将其加载到上下文中。这是一个记录项目规范、编码约定和开发流程的绝佳位置。

创建 CLAUDE.md 文件：

在项目根目录创建 CLAUDE.md 文件，内容可以包括以下方面：

# 项目说明

这是一个使用 React 和 TypeScript 构建的电子商务平台。

## 开发环境

- Node.js 20+
- PostgreSQL 15
- Redis 7

## 代码风格

- 使用 TypeScript 严格模式
- 组件使用函数式组件和 Hooks
- 样式使用 Tailwind CSS
- 遵循 Airbnb JavaScript 风格指南

## 测试要求

- 所有新功能必须有对应的单元测试
- 测试覆盖率不低于 80%
- 使用 Jest 和 React Testing Library

## Git 工作流

- 主分支：`main`
- 开发分支：`develop`
- 功能分支：`feature/xxx`
- Bug 修复分支：`fix/xxx`
- 使用 Squash Merge 合并 PR

## 常用命令

- 安装依赖：`npm install`
- 运行开发服务器：`npm run dev`
- 运行测试：`npm test`
- 代码检查：`npm run lint`

## 注意事项

- API 密钥存储在 `.env.local` 中，切勿提交到版本控制
- 数据库迁移文件需要手动审核后再执行
- 生产环境部署需要经过代码审查

CLAUDE.md 的最佳实践：

记录常用的 bash 命令可以减少重复解释，提高沟通效率。记录项目的核心文件和关键函数位置，帮助 Claude Code 快速定位。明确代码风格指南和测试要求，确保 Claude Code 生成的代码符合项目标准。描述 Git 工作流规范，确保版本控制操作符合团队要求。列出开发环境配置信息，避免因环境问题导致的错误。

5.2 模型选择与切换

Claude Code 支持多种 Claude 模型，不同模型在能力和价格上有所差异，用户可以根据任务复杂度选择合适的模型。

可用模型：

模型	输入价格	输出价格	适用场景
Claude Opus 4	$15/百万 token	$75/百万 token	复杂推理、高难度任务
Claude Sonnet 4	$3/百万 token	$15/百万 token	日常开发、高性价比

切换模型命令：

/model opus      # 切换到 Opus 模型
/model sonnet    # 切换到 Sonnet 模型

或者在交互中直接说明：

请使用 Opus 模型来处理这个复杂的设计模式问题。

模型选择建议：

对于简单的代码编写、调试和重构任务，Sonnet 模型已经足够，且成本更低。对于需要复杂逻辑推理、架构设计或处理大型代码库的任务，Opus 模型能提供更好的结果。建议根据任务实际复杂度灵活选择，避免过度使用高成本模型。

5.3 权限管理

Claude Code 提供了细粒度的权限控制，可以限制其执行某些操作的能力，这在使用公共代码库或处理敏感项目时尤为重要。

设置权限：

Claude Code 会在首次尝试执行某些操作时询问权限。用户可以授予或拒绝以下权限：

权限类型	说明
Read-only	只读模式，禁止任何文件修改
Bash	允许执行 Shell 命令
Web fetch	允许从网络获取信息
Edit	允许编辑文件

配置文件权限：

可以通过配置文件来预设权限策略：

# 设置允许执行命令但禁止删除文件
export CLAUDE_ALLOW_BASH=true
export CLAUDE_ALLOW_DELETE=false

5.4 自定义命令

用户可以创建自定义命令来简化常用操作，通过配置文件定义命令别名和快捷方式。

创建自定义命令：

在项目配置文件或全局配置中添加自定义命令定义：

{
  "commands": {
    "test": "npm test -- --coverage",
    "lint": "npm run lint -- --fix",
    "dev": "npm run dev"
  }
}

使用自定义命令：

/test    # 运行测试
/lint    # 运行代码检查并自动修复
/dev     # 启动开发服务器

5.5 多会话并行工作

Claude Code 的创造者 Boris Cherny 分享的一个重要技巧是并行工作流。通过使用 Git worktree，可以在多个分支上并行运行多个 Claude Code 会话。

创建 Git worktree：

git worktree add feature/new-feature develop
git worktree add bugfix/urgent-fix main

在多个 worktree 中工作：

可以为不同的 worktree 创建快捷命令：

# 在 .bashrc 或 .zshrc 中添加
alias wa='cd "$(git worktree list | grep -E "^\+.*wa\$" | cut -d" " -f1)"'
alias wb='cd "$(git worktree list | grep -E "^\+.*wb\$" | cut -d" " -f1)"'

这种并行工作方式可以显著提高开发效率，特别适合需要同时处理多个任务的场景。

六、VS Code 集成

除了命令行使用，Claude Code 还可以集成到 VS Code 编辑器中，提供更便捷的开发体验。这种集成方式结合了 Claude Code 的 AI 能力和 VS Code 的可视化编辑优势。

6.1 安装 VS Code 扩展

安装步骤：

打开 VS Code，进入扩展市场（快捷键 Ctrl+Shift+X），搜索 “Claude Code”，找到官方扩展并点击安装。安装完成后，需要配置扩展设置以连接 Claude Code CLI。

配置扩展：

安装完成后，在 VS Code 设置中找到 Claude Code 相关配置项，确保正确配置了 CLI 路径。通常情况下，扩展会自动检测已安装的 Claude Code。

6.2 使用方法

启动 Claude Code 面板：

安装扩展后，VS Code 右侧边栏或面板区域会出现 Claude Code 图标。点击图标即可打开 Claude Code 面板，可以直接与 Claude 进行对话。

通过终端访问：

也可以通过 VS Code 内置终端直接使用 claude 命令，效果与独立终端相同。

在代码编辑器中使用：

选中代码片段后，右键菜单中会显示 “Ask Claude” 选项，可以直接对选中的代码进行操作：

解释这段代码
重构这个函数
添加注释
修复这个 bug

6.3 快捷键设置

为了提高效率，可以设置快捷键来快速调用 Claude Code 功能：

{
  "key": "ctrl+alt+c",
  "command": "claude-code.chat"
}

设置后，按下快捷键即可快速打开 Claude Code 对话框。

七、最佳实践与效率技巧

本节汇总了来自 Anthropic 内部团队和社区开发者的实践经验，帮助用户更高效地使用 Claude Code。

7.1 提示工程技巧

明确具体的需求：

模糊请求："帮我改进代码"
清晰请求："请帮我重构这个函数，将其拆分为更小的单元测试友好的函数，目标是提高代码可读性和可维护性，同时保持功能不变。"

提供足够的上下文：

"在 src/user/auth.ts 文件中的 login 函数中，有一处错误：用户在输入正确密码时仍然无法登录。请帮我调试这个问题。"

分步骤提出复杂需求：

对于复杂任务，不要期望一次性完成所有要求，而是分步骤进行：

步骤1：首先帮我理解这个模块的架构
步骤2：现在帮我设计一个性能优化方案
步骤3：根据设计方案帮我实现优化

7.2 成本控制策略

使用 CLAUDE.md 控制上下文：

通过精确的 CLAUDE.md 配置，避免加载不必要的文件到上下文中，减少 token 消耗。

选择合适的模型：

对于简单任务使用 Sonnet 模型，只在真正需要时才切换到 Opus 模型。

定期压缩对话：

/compact

使用 /compact 命令压缩对话历史，在保留关键信息的同时减少 token 消耗。

设置使用配额：

可以在 Anthropic Console 中设置使用配额和警告阈值，避免意外超支。

7.3 工作流程优化

先规划后执行：

对于复杂任务，先让 Claude Code 制定计划，确认后再执行：

"请先给我一个实现这个功能的计划，包括需要修改哪些文件、预期的代码结构等。计划通过后再开始编码。"

善用并行工作：

在等待 Claude Code 执行任务时，可以同时处理其他事情，或者使用多个会话并行工作。

建立项目模板：

为常用项目类型创建标准化的 CLAUDE.md 模板，减少重复配置工作。

7.4 安全实践

审查生成的代码：

Claude Code 生成的代码应该像任何其他代码一样经过审查，不要盲目信任其输出。

敏感信息处理：

切勿在对话中泄露 API 密钥、密码、数据库连接字符串等敏感信息。使用环境变量来管理这些信息。

限制危险操作：

对于删除文件、修改生产环境配置等危险操作，保持谨慎，确认操作的影响范围。

八、常见问题与故障排除

本节汇总了使用 Claude Code 时可能遇到的常见问题及其解决方案。

8.1 安装问题

问题：安装后命令找不到

如果执行 claude --version 提示命令不存在，可能需要手动将 Claude Code 添加到 PATH 环境变量中。

Linux/macOS 解决方案：

# 查找安装位置
which claude
# 或
find /usr -name claude 2>/dev/null

# 如果在 node_modules 中
export PATH="$PATH:$(npm root -g)/@anthropic-ai/claude-code"

Windows 解决方案：

检查 Node.js 全局模块路径是否在 PATH 中：

npm config get prefix
# 将返回的路径添加到系统 PATH 环境变量

问题：权限被拒绝

在 Linux/macOS 上可能遇到权限问题，可以使用以下方法解决：

# 使用 sudo 安装（不推荐）
sudo npm install -g @anthropic-ai/claude-code

# 或者修复 npm 权限
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

8.2 身份验证问题

问题：OAuth 登录失败

如果 OAuth 登录过程中出现问题，尝试以下步骤：

1. 确保网络连接正常
2. 清除浏览器缓存后重试
3. 尝试使用无痕模式登录
4. 检查是否被浏览器广告拦截插件阻止

问题：API 密钥无效

如果配置了 API 密钥但无法使用：

1. 确认 API 密钥格式正确（以 sk- 开头）
2. 检查密钥是否已过期或被撤销
3. 验证 API 密钥是否有足够的余额
4. 确认 ANTHROPIC_BASE_URL 配置正确（如果使用自定义服务）

8.3 使用问题

问题：响应速度慢

响应速度慢可能有多种原因：

1. 网络问题：检查网络连接，尝试使用代理
2. 模型选择：切换到更快的模型（如 Sonnet）
3. 上下文过大：使用 /compact 压缩对话历史
4. 复杂任务：将大任务拆分为小任务

问题：文件操作失败

如果 Claude Code 无法读写文件：

1. 检查文件路径是否正确
2. 确认用户对文件有读写权限
3. 检查文件是否被其他程序锁定
4. 确认路径格式符合系统要求（Windows 使用反斜杠）

问题：执行命令失败

命令执行失败时：

1. 查看完整的错误输出
2. 确认命令语法正确
3. 检查相关工具是否已安装（如 git、npm）
4. 验证工作目录是否正确

8.4 性能优化

减少上下文加载时间：

1. 优化 CLAUDE.md，只包含必要信息
2. 使用 .claudeignore 文件排除无关文件
3. 定期清理不需要的历史会话

提高响应质量：

1. 提供更精确的问题描述
2. 明确期望的代码风格和结构
3. 指定需要遵循的框架或库版本

九、卸载与更新

9.1 更新 Claude Code

手动更新：

claude update

执行更新命令会自动检查并安装最新版本。

通过包管理器更新：

如果使用 Homebrew：

brew upgrade claude

如果使用 npm：

npm update -g @anthropic-ai/claude-code

9.2 卸载 Claude Code

使用官方卸载脚本：

curl -fsSL https://claude.ai/uninstall.sh | bash

手动卸载：

# npm 安装的
npm uninstall -g @anthropic-ai/claude-code

# 删除配置文件
rm -rf ~/.claude
rm -rf ~/.config/claude

Windows 卸载：

通过控制面板的"添加/删除程序"找到 Claude Code 进行卸载，然后手动删除残留的配置文件夹。

十、总结

Claude Code 作为一款强大的代理式 AI 编程工具，通过命令行界面为开发者提供了前所未有的编程体验。本文从系统要求、安装配置、基础使用、进阶功能、最佳实践到故障排除，全面介绍了 Claude Code 的各个方面。

通过合理使用 CLAUDE.md 配置项目规范、选择合适的模型、利用多会话并行工作，以及遵循安全实践和成本控制策略，开发者可以充分发挥 Claude Code 的潜力，显著提升开发效率。

建议新用户从基础功能开始学习，逐步掌握进阶技巧，并根据实际工作流程定制适合自己的使用方式。AI 编程工具是辅助而非替代，保持批判性思维，对 AI 生成的代码进行适当的审查和测试，是确保代码质量的关键。

随着 AI 技术的不断发展，Claude Code 也在持续更新和完善。建议定期关注官方文档和更新日志，了解新功能和最佳实践的变化。