Claude Code 完整教程：Anthropic 官方 CLI 编程智能体

📅 2026-06-02 · 📄 约 3500 字

前言

Claude Code 是 Anthropic 官方推出的终端 AI 编程智能体，基于 Claude 3.7 模型构建。与 Web 端的 Claude 对话助手不同，Claude Code 完全运行在本地终端环境，能够深入理解项目代码库、读取和编辑文件、执行 Shell 命令、管理 Git 工作流。它是程序员的贴身Coding搭档——不管是修复 Bug、重构代码、编写测试，还是自动化日常开发任务，Claude Code 都能以自然语言驱动的方式完成。

Claude Code 工作流程图

Claude Code 的核心优势在于它对项目上下文的深度理解——它能读取整个代码库、理解项目结构、自动追踪跨文件依赖关系。与简单的代码补全工具相比，它的操作粒度更粗（直接编辑文件、运行命令），适合处理需要多步推理的复杂编程任务。目前 Claude Code 支持 macOS、Linux、Windows（通过 WSL）以及多种 IDE 集成（VS Code、JetBrains）。

环境准备

在开始安装 Claude Code 之前，需要确认本地环境满足以下要求：

  • 操作系统：macOS 10.15+、Ubuntu 18.04+/Debian 10+、Windows 11（WSL2）
  • Node.js：18.0 或更高版本（安装 CLI 所必需）
  • 网络：能够访问 Anthropic API 或第三方兼容端点
  • 账号：Anthropic API Key（含免费额度）或 Claude 订阅账号
  • 磁盘：至少 200MB 可用空间

对于国内用户，建议配置科学上网或使用 MiniMax 等第三方兼容 API 端点。

安装步骤

Claude Code 提供多种安装方式，开发者可以根据自己的系统环境选择最适合的方式。

方式一：官方安装脚本（推荐）

在终端执行官方安装脚本，自动检测系统架构并完成安装：

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

对于中国大陆用户，如果官方脚本安装失败，可以尝试手动安装：先从 GitHub Releases 页面下载对应架构的二进制文件，赋予执行权限后放置到 PATH 目录下。

方式二：Homebrew（macOS/Linux）

通过 Homebrew 包管理器安装：

brew install --cask claude-code

方式三：npm（全局安装）

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

注意：npm 安装方式已不推荐，官方推荐使用安装脚本。如果 npm 安装遇到权限问题（EACCES），需要先修复 npm 全局目录权限。

方式四：Windows（PowerShell）

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

或使用 WinGet：

winget install Anthropic.ClaudeCode

认证配置

安装完成后，需要进行身份认证才能使用 Claude Code。

方式一：API Key 认证（适合 API 用户）

设置环境变量 ANTHROPIC_API_KEY：

export ANTHROPIC_API_KEY="sk-ant-..."  # 你的 API Key

建议将这一行添加到 ~/.bashrc 或 ~/.zshrc 以便永久生效。

方式二：OAuth 登录（适合订阅用户）

claude auth login

执行后会打开浏览器进行 OAuth 认证流程。认证完成即可在终端使用。

方式三：使用第三方 API 端点

如果使用 MiniMax 等第三方服务，需要配置两个环境变量：

export ANTHROPIC_BASE_URL="https://api.minimaxi.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="sk-cp-..."  # 注意是 AUTH_TOKEN 不是 API_KEY

基本使用

安装和认证完成后，在项目目录下直接运行 claude 即可启动交互模式：

cd /path/to/your/project
claude

Claude Code 会分析当前目录的结构，首次使用时会询问是否信任该目录（信任后才允许执行文件操作和 Shell 命令）。

交互模式 vs 打印模式

Claude Code 支持两种运行模式：

  • 交互模式：在终端启动一个 TUI 会话，可以多轮对话、实时观察 Claude 的思考和操作过程，适合复杂任务
  • 打印模式（-p）：单次执行任务后自动退出，适合自动化脚本和 CI/CD 集成

打印模式示例：

claude -p "解释 auth.py 中的 JWT 验证逻辑" --max-turns 3

核心功能与实战场景

1. 代码阅读与解释

Claude Code 能够深入理解代码库，回答关于代码逻辑的问题：

claude -p "分析 src/auth/ 目录下的认证流程，说明 token 验证的完整链路" --max-turns 5

2. 代码编辑与重构

直接描述你想做的修改，Claude Code 会自动完成：

claude -p "将 user_service.py 中的同步数据库查询改为异步，使用 async/await 模式" --max-turns 10

3. Bug 修复

粘贴错误信息或描述问题现象，Claude Code 会定位并修复：

claude -p "修复登录后 session 过期的问题。错误信息：TypeError: Cannot read property 'id' of undefined at UserService.getUser" --max-turns 10

4. 自动化脚本

描述需求，Claude Code 生成完整脚本：

claude -p "写一个 Node.js 脚本，遍历 src/components 目录下所有 .jsx 文件，提取其中的 props 定义并输出到一个 props.json 文件" --max-turns 5

5. Git 工作流

Claude Code 原生支持 Git，可以自动处理提交、分支、Diff 等操作：

# 提交当前更改
claude -p "提交所有修改，commit message 简洁明了" --max-turns 3

权限模式与安全

Claude Code 有严格的权限控制系统，首次在目录中使用时会询问信任确认：

  • 信任目录：允许 Claude 读取文件、执行命令、写文件
  • 跳过权限：通过 --dangerously-skip-permissions 标志可以在脚本中跳过交互确认（慎用）

建议在使用前仔细阅读官方文档的权限模式说明，了解各模式允许的操作边界。

IDE 集成

Claude Code 不仅可以在终端使用，还深度集成了主流 IDE：

  • VS Code：官方提供 VS Code 扩展，在编辑器内直接调用 Claude
  • JetBrains：支持 IntelliJ IDEA、PyCharm、WebStorm 等 JetBrains 全家桶
  • 终端内联：在终端中输入 @claude 引用文件或代码片段

常见问题

Q: 安装后提示 "command not found"

检查 PATH 环境变量是否包含 npm 全局 bin 目录。修复方法：

mkdir -p ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Q: API Key 认证失败（403 错误）

确认使用的是 ANTHROPIC_AUTH_TOKEN 而不是 ANTHROPIC_API_KEY。如果使用第三方 API，验证 BASE_URL 是否正确配置。

Q: Claude Code 权限被拒绝

检查当前目录的读写权限，确保 Claude 有权限执行所需操作。

总结

Claude Code 是目前最强大的终端 AI 编程智能体之一，与 OpenAI Codex CLI 并列为开源社区最受欢迎的两大 CLI 编程工具。它的优势在于对项目上下文的深度理解、Anthropic 模型强大的推理能力，以及对多种平台和 IDE 的广泛支持。无论是个人开发者日常编码，还是团队集成到 CI/CD 流程，Claude Code 都能显著提升编程效率。建议从今天开始在项目目录中运行 claude，体验 AI 编程的便捷与高效。