Claude Code 下载与使用指南

一、Claude Code 是什么

Claude Code 是 Anthropic 推出的终端 AI 编程智能体。它运行在你的本地终端中，能够直接读取、编辑项目文件，执行终端命令，帮你完成各类开发任务。

核心能力：

• 根据自然语言描述构建功能
• 分析代码库并回答问题
• 调试和修复 Bug
• 执行 Git 操作（提交、分支、解决冲突）
• 自动化繁琐任务（lint 修复、写 release notes 等）
• 通过 MCP 协议连接外部数据源（Google Drive、Figma、Slack 等）

---

二、系统要求

项目	要求
操作系统	macOS / Linux / Windows（原生支持或 WSL）
Node.js	>= 18.0（仅 npm 安装方式需要）
网络	需要访问 Anthropic API 服务
账号	Claude.ai 订阅账号（推荐）或 Claude Console API 账号

---

三、安装

方式一：原生安装脚本（官方推荐，无需 Node.js）

macOS / Linux / WSL：

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

Windows PowerShell：

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

Windows CMD：

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

原生安装会自动处理依赖，并支持后台自动更新。

方式二：npm 安装

需要先安装 Node.js 18+：

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

# 验证
claude --version

方式三：Homebrew（macOS）

brew install --cask claude-code

方式四：npx 免安装直接运行

npx @anthropic-ai/claude-code

首次运行会自动下载并缓存，后续运行使用缓存版本。

Node.js 安装（前置步骤，仅 npm 方式需要）

# macOS
brew install node

# Ubuntu / Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证
node -v   # v18+ 或 v20+

---

四、登录认证

首次登录

安装完成后，在项目目录中运行 claude，首次使用会提示登录：

cd /path/to/your/project
claude

支持两种账号类型：

账号类型	说明	推荐度
Claude.ai	使用订阅计划（Pro/Team/Enterprise）	推荐
Claude Console	使用 API 预付费额度	备选

登录后凭据会保存在本地，后续无需重复登录。

切换账号

在 Claude Code 交互模式中输入：

/login

按提示切换账号。

API Key 方式（可选）

如果你使用 Claude Console 账号，也可以通过环境变量设置 API Key：

export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

---

五、基本使用

5.1 启动交互模式

# 进入项目目录后启动
cd /path/to/your/project
claude

启动后会看到 Claude Code 的交互提示符，直接用自然语言输入需求即可。

5.2 一次性任务

# 直接传入任务描述，执行完自动退出
claude "fix the build error"

# 一次性查询，不进入交互模式
claude -p "explain this function"

5.3 继续和恢复对话

# 继续最近一次对话
claude -c

# 恢复之前的某次对话（从列表中选择）
claude -r

5.4 Git 集成

# 让 Claude 自动生成 commit
claude commit

5.5 管道模式（Unix 哲学）

Claude Code 支持管道输入，非常灵活：

# 监控日志并让 Claude 分析异常
tail -f app.log | claude -p "如果发现异常模式，告诉我"

# 翻译代码中的文本字符串
claude -p "将项目中的文本字符串翻译为法语，并提交 PR"

---

六、常用斜杠命令

在交互模式中可使用以下命令：

命令	说明
/help	查看所有可用命令
/clear	清空当前对话历史
/login	切换登录账号
/bug	报告 Bug
/compact	压缩对话上下文，节省 token
exit 或 Ctrl+C	退出 Claude Code

---

七、核心使用场景

7.1 理解代码库

> 这个项目是做什么的？
> 项目用了哪些技术栈？
> 主入口文件在哪里？
> 解释一下目录结构

Claude Code 会自动读取项目文件来回答，无需手动提供上下文。

7.2 编写和修改代码

> 在 main.py 中添加一个 hello world 函数
> 给用户注册表单添加输入验证
> 将认证模块重构为使用 async/await

Claude Code 会：

1. 找到相关文件
2. 展示拟修改的内容
3. 请求你的确认
4. 执行修改

7.3 调试和修复 Bug

> 用户输入错误密码后看到白屏，帮我修复这个 bug
> 运行测试并告诉我哪些失败了

7.4 编写测试

> 为 calculator 模块编写单元测试
> 给 API 接口写集成测试

7.5 Git 操作

> 我修改了哪些文件？
> 用描述性消息提交我的更改
> 创建一个名为 feature/login 的新分支
> 帮我解决合并冲突

7.6 代码审查

> 审查我的更改并给出改进建议
> 检查代码中是否有安全漏洞

---

八、CLAUDE.md（项目记忆）

在项目根目录创建 CLAUDE.md 文件，写入项目上下文信息。Claude Code 每次启动时会自动读取，相当于项目的"记忆"。

# CLAUDE.md

## 项目概述
这是一个基于 FastAPI 的电商后台 API 服务。

## 技术栈
- 后端：Python 3.11 + FastAPI + SQLAlchemy
- 数据库：PostgreSQL + Redis
- 测试：pytest + httpx

## 编码规范
- 使用 Black 格式化代码
- 类型注解必须完整
- API 路由放在 app/api/ 目录下
- 不要修改 alembic/versions/ 下的迁移文件

## 常用命令
- 启动开发服务器：uvicorn app.main:app --reload
- 运行测试：pytest
- 数据库迁移：alembic upgrade head

类似 OpenAI Codex 的 AGENTS.md，但文件名不同。

---

九、MCP 服务器（Model Context Protocol）

Claude Code 支持连接 MCP 服务器，扩展能力边界：

• 读取 Google Drive 中的设计文档
• 更新 Jira 中的工单
• 查询 Figma 设计稿
• 读取 Slack 消息
• 连接自定义开发工具

配置方式详见官方文档：https://docs.claude.com/en/docs/claude-code/mcp

---

十、进阶功能

10.1 Headless 模式（非交互）

用于 CI/CD 自动化场景：

claude -p "检查代码风格问题并自动修复" --output-format json

10.2 GitHub Actions 集成

Claude Code 可以在 GitHub Actions 中自动运行，用于自动代码审查、PR 描述生成等。

10.3 VS Code 插件（Beta）

如果你更喜欢图形界面，可以安装 Claude Code 的 VS Code 扩展，在编辑器侧边栏中直接使用。

10.4 云端部署

支持通过 Amazon Bedrock 或 Google Vertex AI 托管模型：

• Amazon Bedrock 配置
• Google Vertex AI 配置

---

十一、安全与权限

• 文件修改需确认：Claude Code 在修改文件前会展示变更内容并请求你确认。
• Accept All 模式：可以开启自动接受模式，跳过逐次确认（谨慎使用）。
• 企业级安全：支持 SSO、权限管理、数据合规。
• 数据使用：详见 隐私政策。

---

十二、常用命令速查

命令	说明
claude	启动交互模式
claude "任务描述"	执行一次性任务
claude -p "查询"	一次性查询后退出
claude -c	继续最近对话
claude -r	恢复历史对话
claude commit	自动生成 Git 提交
claude --version	查看版本
claude --help	查看帮助

---

十三、常见问题

Q: 安装后运行 claude 提示命令找不到？

# 确认安装路径在 PATH 中
which claude

# 如果找不到，手动添加（原生安装通常在 ~/.claude/bin/）
export PATH="$HOME/.claude/bin:$PATH"
echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.zshrc

Q: 如何升级？

# 原生安装方式会自动更新
# npm 方式手动升级
npm update -g @anthropic-ai/claude-code

# Homebrew
brew upgrade claude-code

Q: 如何卸载？

# npm
npm uninstall -g @anthropic-ai/claude-code

# Homebrew
brew uninstall --cask claude-code

# 原生安装
rm -rf ~/.claude

Q: 免费用户能用吗？

Claude Code 需要 Claude Pro / Team / Enterprise 订阅，或 Claude Console 的 API 预付费额度。免费版 Claude 账号不支持。

Q: 和 OpenAI Codex 有什么区别？

维度	Claude Code	OpenAI Codex CLI
厂商	Anthropic	OpenAI
模型	Claude (Sonnet/Opus)	GPT / Codex
认证	Claude.ai 订阅或 API Key	ChatGPT 订阅或 API Key
项目记忆	CLAUDE.md	AGENTS.md
MCP 支持	原生支持	原生支持
管道模式	支持	支持

---

十四、实用技巧

1. 写好 CLAUDE.md：在项目根目录放一个详细的 CLAUDE.md，Claude 的输出质量会显著提升。
2. 任务描述要具体：不要说"修复 bug"，要说"修复用户输入错误密码后白屏的问题"。
3. 分步执行复杂任务：将大任务拆成小步骤，逐步确认后再继续。
4. 善用 git：让 Claude 操作前先提交当前代码，出问题可以随时回退。
5. 用 Tab 补全：按 Tab 键可以补全命令和文件路径。
6. 用方向键翻历史：按上箭头可以查看之前的命令历史。
7. 管道组合：利用 Unix 管道将 Claude Code 与其他工具组合使用。

---