ClaudeCode使用攻略

2026-01-28 14:21:59

Claude Code 使用攻略：从入门到精通的完整指南

Claude Code 是 Anthropic 推出的终端原生 AI 编程助手，旨在通过自然语言指令深度融入开发工作流，实现代码生成、调试、重构、Git 操作等全流程自动化。与传统的代码补全工具（如 Copilot）不同，Claude Code 具备代理能力（Agentic）——它能自主规划多步骤任务（如“修复 bug 并创建 PR”），而非仅提供代码片段。本文将覆盖 Claude Code 的核心概念、安装配置、使用技巧、常见错误及最佳实践，助你快速掌握这一工具。

一、Claude Code 核心概念

在正式使用前，需明确 Claude Code 的几个关键特性，避免与其他工具混淆：

终端原生：直接在终端（Terminal/PowerShell/CMD）中运行，无需额外 IDE 插件（但支持与 VS Code、JetBrains 等 IDE 集成）。
代理模式：能主动执行命令（如 git commit、npm test）、修改文件、调用工具（如 Puppeteer 截图），而非仅生成代码。
上下文感知：自动扫描项目目录，理解代码结构、依赖关系和编码规范（需通过 CLAUDE.md 强化）。
多模态支持：可接受文本、图像（如截图）、URL 等输入，输出代码、文档或操作指令。

二、安装与配置

1. 系统要求

操作系统：macOS 10.15+、Ubuntu 20.04+/Debian 10+、Windows 10+（需 WSL 或 Git for Windows）。
软件依赖：Node.js 18+（仅 NPM 安装需要）、npm（随 Node.js 自带）。
网络：需联网（认证和 AI 处理需要），国内用户可能需要代理或使用中转服务。

2. 安装方式

Claude Code 支持多种安装方式，推荐优先使用官方脚本或包管理器：

（1）macOS/Linux/WSL

# 安装稳定版本（默认）
  curl -fsSL https://claude.ai/install.sh | bash
  
  # 安装最新版本（ bleeding edge ）
  curl -fsSL https://claude.ai/install.sh | bash -s latest
  
  # 安装特定版本（如 1.0.58 ）
  curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

或使用 Homebrew（macOS/Linux）：

brew install --cask claude-code

（2）Windows

PowerShell：

# 安装稳定版本
  irm https://claude.ai/install.ps1 | iex
  
  # 安装最新版本
  & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

CMD：

REM 安装稳定版本
  curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

（3）NPM 安装（备选）

若偏好 NPM，可使用以下命令（需 Node.js 18+）：

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

3. 配置与登录

（1）首次启动

安装完成后，在终端输入 claude 启动，会提示登录：

方式 1：账号验证：使用 Claude Pro/Max 订阅账号登录（需魔法），支持网页授权。
方式 2：API 验证：使用 Anthropic API 密钥（sk- 开头），适合国内用户（需配置中转服务）。

（2）国内用户配置（关键）

由于 Claude 官方服务在国内受限，推荐使用中转 API 或镜像解决网络问题：

中转 API：通过第三方服务（如 https://moacode.com）转发请求，配置环境变量：

# Windows（系统变量）
  ANTHROPIC_AUTH_TOKEN=sk-你的密钥
  ANTHROPIC_API_KEY=sk-你的密钥
  ANTHROPIC_BASE_URL=https://moacode.com
  CLAUDE_CODE_MAX_OUTPUT_TOKENS=32000  # 解决输出长度限制
  
  # macOS/Linux（~/.zshrc 或 ~/.bashrc）
  echo 'export ANTHROPIC_AUTH_TOKEN="sk-你的密钥"' >> ~/.zshrc
  echo 'export ANTHROPIC_API_KEY="sk-你的密钥"' >> ~/.zshrc
  echo 'export ANTHROPIC_BASE_URL="https://moacode.com"' >> ~/.zshrc
  source ~/.zshrc

镜像：使用国内镜像（如 http://h5ma.cn/bxa），无需魔法，但需注意镜像的稳定性。

三、核心使用技巧

Claude Code 的交互方式以自然语言指令为主，结合斜杠命令（如 /init、/clear）和上下文管理，能大幅提升开发效率。以下是关键技巧：

1. 项目初始化：`CLAUDE.md` 的作用

CLAUDE.md 是 Claude Code 的项目记忆文件，用于存储代码结构、编码规范、依赖信息等上下文，确保 AI 生成的代码符合项目要求。必须放在项目根目录，并通过 Git 提交，供团队成员共享。

（1）创建 `CLAUDE.md`

在项目根目录运行以下命令，Claude 会自动生成初始内容：

claude /init

生成的文件包含：

项目结构（如 src/、components/）；
依赖信息（如 package.json 中的框架）；
编码规范（如 TypeScript 严格模式、命名规则）。

（2）优化 `CLAUDE.md`

为了让 AI 更准确理解项目，需补充以下内容：

技术栈：明确前端（如 Next.js）、后端（如 Express）、数据库（如 PostgreSQL）等技术选型；
编码规范：如“使用函数组件和 Hooks”“API 响应格式为 { success: boolean, data?: any }”；
项目结构：如 src/app（页面）、src/services（业务逻辑）、src/types（类型定义）；
敏感操作规则：如“密码必须哈希存储”“Token 需设置过期时间”。

示例 CLAUDE.md：

# 项目上下文
  
  ## 技术栈
  - 前端：Next.js 14 + TypeScript + Tailwind CSS
  - 后端：Node.js + Express + Prisma
  - 数据库：PostgreSQL
  - 认证：JWT
  
  ## 编码规范
  - 使用函数组件和 Hooks；
  - TypeScript 严格模式（`strict: true`）；
  - API 响应格式：`{ success: boolean, data?: any, error?: string }`；
  - 错误处理：使用 `try-catch`，并返回统一错误格式。
  
  ## 项目结构
  src/
  ├── app/          # Next.js 页面（如 `app/page.tsx`）
  ├── components/   # React 组件（如 `components/Button.tsx`）
  ├── services/     # 业务逻辑（如 `services/user.service.ts`）
  ├── types/        # TypeScript 类型（如 `types/user.type.ts`）
  └── utils/        # 工具函数（如 `utils/jwt.util.ts`）
  
  
  ## 敏感操作规则
  - 密码必须使用 `bcrypt` 哈希存储（盐值 rounds=10）；
  - 重置 Token 需设置 1 小时过期时间；
  - 所有用户输入必须经过验证（如使用 `zod`）。

2. 常用斜杠命令

Claude Code 提供了多个斜杠命令（以 / 开头），用于快速执行常见任务：

命令	作用
`/init`	创建/更新 `CLAUDE.md`，初始化项目上下文
`/clear`	清空当前对话上下文，避免信息过载
`/help`	查看所有命令及用法
`/cost`	显示当前会话的 token 使用量及预估费用
`/review`	审查指定文件或代码变更（如 `/review src/components/Button.tsx`）
`/bug`	报告 bug（将当前会话内容发送给 Anthropic）

3. 上下文管理

Claude Code 的性能依赖于上下文质量，需避免以下问题：

上下文丢失：若对话中断或新开会话，AI 可能“忘记”之前的技术选型（如从 Prisma 换成 Mongoose）。解决方法：
- 每次对话都重申关键信息（如“继续开发电商系统，技术栈为 Next.js + Prisma + PostgreSQL”）；
- 使用 CLAUDE.md 存储项目上下文，每次开发前运行 claude /init 加载。
上下文过载：若对话包含过多无关信息（如早期的错误日志），AI 可能忽略关键指令。解决方法：
- 使用 /clear 清空上下文，仅保留当前任务的相关信息；
- 将长对话拆分为多个短对话（如“先实现用户模块，再实现商品模块”）。

4. 代理模式：让 AI 执行任务

Claude Code 的代理模式是其核心优势，能让 AI 自主完成多步骤任务（如“修复 bug 并创建 PR”）。以下是典型流程：

（1）示例：修复登录 Bug

假设你遇到“登录时验证码无效”的问题，可按以下步骤操作：

描述问题：

claude "登录时验证码无效，验证码存储在 Redis 中，有效期 5 分钟"

请求分析：

claude "分析验证码无效的原因，可能的错误点包括：Redis 连接、验证码生成逻辑、验证逻辑"

执行修复：

claude "修复验证码验证逻辑，确保从 Redis 中获取的验证码与用户输入一致"

验证修复：

claude "运行登录测试，确认验证码有效"

提交代码：

claude "提交修复代码，并创建 PR，描述为‘修复登录验证码无效问题’"

（2）注意事项

权限管理：默认情况下，Claude 会请求权限（如修改文件、运行命令），需手动确认。可通过 /permissions 命令预设允许的命令（如 git commit），减少重复确认。
安全检查：对于敏感操作（如修改数据库、发送邮件），需让 AI 生成安全检查清单（如“输入验证是否完善？”“敏感数据是否加密？”），避免安全漏洞。

四、常见错误及解决方法

使用 Claude Code 时，可能遇到以下常见错误，以下是解决方法：

1. `401 Unauthorized`（无效令牌）

原因：ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY 配置错误，或密钥过期。
解决方法：
- 检查环境变量是否正确（如 ANTHROPIC_AUTH_TOKEN 是否为 sk- 开头）；
- 删除 C:\Users\你的用户名\.claude 目录下的 settings.json，重新运行 claude 并登录；
- 若使用中转 API，确认中转服务的密钥是否有效。

2. `403 Forbidden`（请求被拒绝）

原因：环境变量未配置，或中转服务限制。
解决方法：
- 检查 ANTHROPIC_BASE_URL 是否正确（如 https://moacode.com）；
- 确认中转服务是否支持 Claude Code（如 moacode.com 是否正常运行）；
- 尝试更换网络（如手机热点），避免 IP 被限制。

3. `Request Timeout`（请求超时）

原因：网络问题（如延迟高），或任务过于复杂（如处理大文件）。
解决方法：
- 检查网络连接（如 ping https://moacode.com）；
- 将复杂任务拆分为多个子任务（如“先处理用户模块，再处理商品模块”）；
- 增加超时时间（如设置 CLAUDE_TIMEOUT=600，单位秒）。

4. `Overloaded Error`（服务器超载）

原因：Claude 官方服务器负载过高（如高峰期）。
解决方法：
- 等待一段时间（如 10-30 分钟）再试；
- 切换模型（如从 claude-opus-4 换成 claude-sonnet-4，性能稍弱但更稳定）；
- 查看 Claude 服务状态（如 status.anthropic.com）。

5. `Tool Call Error`（工具调用错误）

原因：AI 调用的工具（如 git、npm）出现异常（如命令不存在、权限不足）。
解决方法：
- 检查工具是否正确安装（如 git --version、npm --version）；
- 确认当前用户是否有足够权限（如 sudo 权限，但不推荐使用 sudo 运行 Claude）；
- 重试命令（如 claude /retry），或手动执行命令（如 git commit -m "fix"）。

五、最佳实践

为了最大化 Claude Code 的效率，需遵循以下最佳实践：

1. 永远审查 AI 生成的代码

AI 生成的代码可能存在安全隐患（如明文存储密码）、边界情况遗漏（如未处理空值）或性能问题（如循环嵌套过深）。解决方法：

代码审查：仔细检查 AI 生成的代码，重点关注敏感操作（如密码处理、数据库查询）；
安全检查清单：对于涉及敏感操作的代码，使用以下清单检查：
- 输入验证是否完善（如使用 zod 验证用户输入）；
- 敏感数据是否加密（如密码使用 bcrypt 哈希）；
- 权限检查是否充分（如验证用户是否有权限修改数据）；
- 是否有 SQL 注入风险（如使用 Prisma 的 $queryRaw 时需谨慎）；
- 是否有 XSS 风险（如对用户输入进行转义）。

让 AI 自我审查：使用以下指令让 AI 检查代码安全问题：

claude "审查这段代码的安全问题，特别是：1. 密码处理；2. Token 安全；3. 输入验证；4. 防止暴力攻击"

2. 维护清晰的上下文

使用 CLAUDE.md：将所有项目相关信息（技术栈、编码规范、项目结构）存储在 CLAUDE.md 中，确保 AI 生成的代码符合项目要求；
避免上下文过载：使用 /clear 清空无关上下文，仅保留当前任务的相关信息；
在同一对话中完成相关功能：不要把相关功能拆到多个对话中（如“先实现用户模块，再实现商品模块”），尽量在一个对话里完成，避免上下文丢失。

3. 避免过度依赖 AI

AI 是助手，不是替代品。需理解 AI 生成的代码逻辑，避免“知其然不知其所以然”。解决方法：

注释代码：让 AI 生成的代码包含详细注释（如“// 使用 bcrypt 哈希密码，盐值 rounds=10”）；
学习代码逻辑：对于复杂逻辑（如状态管理、权限控制），需手动梳理流程，确保理解每一步的作用；
记录对话：将重要的对话记录保存（如 conversations/ 目录），方便后续查阅。

4. 使用版本控制

备份代码：使用 Git 提交代码（git commit -m "feat: 添加用户模块"），避免 AI 生成的代码丢失或出错；
回滚代码：若 AI 生成的代码出现问题，可使用 git revert 回滚到之前的版本；
分支管理：使用分支开发新功能（如 feature/user-module），避免影响主分支（main）的稳定性。

六、总结

Claude Code 是一款强大的终端 AI 编程助手，能大幅提升开发效率，但需正确使用：

安装配置：选择合适的安装方式（官方脚本/包管理器），配置国内中转服务（若有需要）；
上下文管理：使用 CLAUDE.md 存储项目信息，避免上下文丢失或过载；
代理模式：让 AI 执行多步骤任务（如修复 bug、创建 PR），但需审查代码；
最佳实践：永远审查 AI 生成的代码，维护清晰的上下文，避免过度依赖 AI。