Claude CLI 工具（Claude Code）安装与使用入门

一、Claude Code 是什么？

Claude Code 是 Anthropic 官方发布的命令行 AI 编程 Agent。与普通的代码补全工具不同，它是一个能在你的终端里自主工作的助手——你用自然语言描述任务，它会读取代码库、制定计划、修改文件、运行测试，直到任务完成。

2025年5月正式公开发布，半年内跃升为开发者最爱的 AI 编程工具（Stack Overflow 2026年调查中好评率46%，远超 Cursor 的19%和 GitHub Copilot 的9%）。截至2026年3月，Claude Code 年化营收超过25亿美元，全球 GitHub 公开提交中约4%由 Claude Code 贡献。

二、环境要求

安装 Node.js（如果还没有）

# macOS（推荐用 nvm 管理版本）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.zshrc   # 或 source ~/.bashrc
nvm install 20
nvm use 20

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

# Windows（在 WSL2 中执行上面的 Ubuntu 命令）
# 不推荐在 Windows CMD/PowerShell 原生环境使用，WSL2 体验更好

三、安装 Claude Code

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

# 验证安装成功
claude --version
# 输出类似：claude 1.x.x

# 查看帮助
claude --help

四、认证方式详解

Claude Code 支持三种认证方式，根据你的情况选择最合适的一种：

方式一：Claude 订阅认证（推荐个人开发者）

如果你已经有 Claude Pro 或 Max 订阅，直接用账号认证，Claude Code 的用量包含在订阅内，不额外计费。

claude login
# 会在浏览器打开 claude.ai 授权页面
# 登录后会生成 setup token，复制粘贴回终端
# 认证完成

认证后 token 保存在 ~/.claude/ 目录，下次启动不需要重新登录。

方式二：API Key 认证（推荐企业 / 按用量付费）

如果你有 Anthropic Console 的 API Key，用环境变量方式认证：

# 临时设置（当前终端会话有效）
export ANTHROPIC_API_KEY="sk-ant-api03-你的key"

# 永久设置（写入 shell 配置文件）
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-你的key"' >> ~/.zshrc
source ~/.zshrc

# 验证认证
claude --print "你好"  # 应该输出 Claude 的回复

方式三：AWS Bedrock / Google Cloud Vertex（企业级）

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
# 确保 AWS CLI 已配置好（aws configure）

# Google Cloud Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=你的GCP项目ID
# 确保 gcloud CLI 已认证（gcloud auth login）

五、第一次运行

# 进入你的项目目录
cd /path/to/your/project

# 启动 Claude Code 交互模式
claude

# 你会看到类似：
# ╭──────────────────────────────────╮
# │ ✻ Welcome to Claude Code!        │
# │ /help for help, /exit to quit    │
# ╰──────────────────────────────────╯
# >_

现在可以用自然语言描述任务了：

> 这个项目是做什么的？帮我快速了解一下代码结构

> 找出所有没有错误处理的 API 接口

> 给 src/utils/validator.js 里的所有函数加上 JSDoc 注释

> 运行测试，如果有失败的，帮我修复

六、核心命令速查

交互模式内的斜杠命令

命令行参数（非交互模式）

# -p / --print：非交互模式，执行单次任务后退出
claude -p "找出 src/ 目录下所有超过200行的文件并列出"

# 管道输入：把其他命令的输出传给 Claude
git diff HEAD~1 | claude -p "为这次变更写一条 Conventional Commits 格式的提交信息"
cat error.log | claude -p "分析这些错误日志，找出最频繁的错误类型和可能原因"

# --model：指定模型
claude --model claude-opus-4-6

# --dangerously-skip-permissions：跳过文件修改确认（谨慎使用，适合 CI/CD）
claude --dangerously-skip-permissions -p "更新所有文件的版权头部注释"

# --output-format：指定输出格式（text/json/stream-json）
claude --output-format json -p "列出项目中所有的 TODO 注释"

# --max-turns：限制最大对话轮数（防止无限循环）
claude --max-turns 10 -p "重构 utils.py"

七、CLAUDE.md 配置详解

CLAUDE.md 是 Claude Code 的项目配置文件，放在项目根目录，每次启动时自动读取。写好它是让 Claude Code 高效工作的关键。

初始化 CLAUDE.md

# 在项目目录里启动 Claude Code 后运行
/init
# Claude Code 会扫描项目并生成一个基础的 CLAUDE.md，然后你来完善它

CLAUDE.md 完整模板

# CLAUDE.md

## 项目简介
[2-3句话说明项目是什么、服务什么用户、解决什么问题]

## 技术栈
- 语言：Python 3.11
- 框架：FastAPI 0.115
- 数据库：PostgreSQL 16 + SQLAlchemy 2.0 + Alembic
- 缓存：Redis 7
- 测试：Pytest + httpx
- 部署：Docker + Kubernetes

## 目录结构
```
app/
├── api/v1/          # API 路由层
├── services/        # 业务逻辑层（主要在这里工作）
├── models/          # SQLAlchemy 数据模型
├── schemas/         # Pydantic 请求/响应模型
├── core/            # 配置、安全、依赖注入
└── utils/           # 工具函数
tests/               # 测试文件，镜像 app/ 结构
```

## 开发规范
### 代码风格
- 所有 public 函数必须有类型注解
- 注释使用 Google Style Docstring
- 行长度上限 100 字符（black 格式化）

### 分层规范
- API 层只做参数校验和路由，不写业务逻辑
- 业务逻辑统一在 services/ 层
- 数据库操作只在 services/ 层，不在 API 层直接查询

### 错误处理
- 统一使用 app/core/exceptions.py 中定义的异常
- 所有外部 API 调用必须有超时和重试机制

### 测试规范
- 新功能必须附测试，覆盖：正常路径、边界情况、错误情况
- 测试文件命名：test_[被测模块名].py
- 使用 pytest fixtures，不要硬编码测试数据

## 常用命令
```bash
# 开发环境
make dev              # 启动开发服务器
make test             # 运行所有测试
make test-cov         # 带覆盖率报告的测试
make migrate          # 运行数据库迁移
make lint             # 运行 ruff + mypy

# 数据库
alembic upgrade head   # 应用所有迁移
alembic revision --autogenerate -m "描述"  # 生成迁移
```

## 禁止事项
- 不要直接修改 alembic/versions/ 目录（除非明确要求）
- 不要在代码中硬编码密钥或密码
- 不要跳过类型注解
- 不要直接提交到 main 分支

## 当前已知问题 / 技术债
- [ ] payment_service.py 的错误处理需要重构（暂不动）
- [ ] tests/integration/ 下的测试还未迁移到新框架

CLAUDE.md 的多级配置

Claude Code 支持多级 CLAUDE.md，实现不同目录的差异化配置：

project-root/
├── CLAUDE.md          # 全局项目配置（所有目录都适用）
├── frontend/
│   └── CLAUDE.md      # 前端专属配置（React、TypeScript 规范等）
└── backend/
    └── CLAUDE.md      # 后端专属配置（Python、API 规范等）

八、权限管理：控制 Claude Code 能做什么

Claude Code 在执行可能影响系统的操作（修改文件、运行命令、网络请求）前，默认会征询你的许可。理解这套权限机制，能让你在安全和效率之间找到平衡：

# Claude Code 请求权限时，你有几个选项：
# y / yes      ——  允许这次操作
# n / no       ——  拒绝这次操作
# always       ——  始终允许这类操作（本次会话内）
# never        ——  始终拒绝这类操作（本次会话内）

# 常用的权限配置场景：

# 1. 允许自动运行测试（不每次确认）
# 在对话开始时说：
"你可以直接运行 pytest，不需要每次都问我"

# 2. 限制只读模式（只能分析，不能修改）
claude --allowedTools "Read,Bash(git log),Bash(git diff)"

# 3. CI/CD 环境完全自动（跳过所有确认）
claude --dangerously-skip-permissions -p "运行完整测试套件"

九、常见安装和使用报错

修复 PATH 问题（最常见）

# 查找 npm 全局 bin 目录
npm config get prefix
# 输出类似：/usr/local 或 /home/user/.nvm/versions/node/v20.x.x

# 把 bin 目录加入 PATH（以 zsh 为例）
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证
which claude
claude --version

十、升级和卸载

# 检查当前版本
claude --version

# 升级到最新版
npm update -g @anthropic-ai/claude-code

# 查看可用版本
npm view @anthropic-ai/claude-code versions --json

# 安装特定版本
npm install -g @anthropic-ai/claude-code@1.x.x

# 卸载
npm uninstall -g @anthropic-ai/claude-code
# 可选：删除配置目录
rm -rf ~/.claude

十一、进阶：自动化脚本集成

#!/bin/bash
# 示例：每次 git commit 前自动让 Claude 审查变更

# .git/hooks/pre-commit（赋予执行权限：chmod +x .git/hooks/pre-commit）

STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(py|js|ts)$')

if [ -z "$STAGED_FILES" ]; then
  exit 0
fi

echo "🤖 Claude Code 正在审查本次提交..."

REVIEW=$(git diff --cached -- $STAGED_FILES | \
  claude --output-format text \
         --max-turns 1 \
         --dangerously-skip-permissions \
         -p "审查这个 diff，如果有严重问题（安全漏洞、数据丢失风险）输出 BLOCK，否则输出 OK。只输出 BLOCK 或 OK，不要其他内容。")

if echo "$REVIEW" | grep -q "BLOCK"; then
  echo "❌ Claude Code 发现严重问题，提交被阻止。运行 'git diff --cached' 查看详情。"
  exit 1
fi

echo "✅ 审查通过"
exit 0

常见问题

Q：Claude Code 和 claude.ai 是同一个账号吗？
是的，用 claude login 时使用的是你的 claude.ai 账号。Claude Code 的用量共享你的 Pro/Max 订阅额度。如果用 API Key 认证，则是独立的 Console 账号，按用量单独计费。

Q：Claude Code 会不会自动上传我的代码到 Anthropic？
Claude Code 会把你的代码（或代码片段）发送到 Anthropic 的 API 进行处理，这是它工作的必要条件。根据 Anthropic 政策，Pro/API 用户的数据默认不用于训练模型。如果处理高度敏感的代码（如未公开的商业逻辑），建议在企业版协议下使用或通过 AWS/GCP 私有化部署。

Q：CLAUDE.md 文件需要提交到 git 吗？
推荐提交。CLAUDE.md 相当于项目的 AI 使用规范文档，提交后团队所有成员都能享受一致的 Claude Code 体验。如果包含敏感信息（如内部系统 URL），可以把敏感部分提取到 ~/.claude/CLAUDE.md（用户级全局配置，不进 git）。

Q：Claude Code 对 token 的消耗大吗，费用如何控制？
复杂任务（如审查整个代码库）会消耗大量 token。控制费用的方法：使用 Pro/Max 订阅（包含在月费内）；用 /compact 定期压缩对话历史；用 /model claude-haiku-4-5-20251001 切换到轻量模型处理简单任务；配置好 .claudeignore 避免扫描无关文件。

总结

安装 Claude Code 的完整流程：安装 Node.js 20 LTS → npm install -g @anthropic-ai/claude-code → claude login（或设置环境变量）→ 进入项目目录运行 claude → 运行 /init 生成 CLAUDE.md → 开始使用。

用好 Claude Code 的关键是写好 CLAUDE.md——把项目背景、技术栈、代码规范、常用命令都写清楚，Claude Code 的输出质量会显著提升。把它当成一个理解你项目的新同事，给它足够的上下文，它才能真正帮上忙。