# Claude Code 零基础入门到实战全攻略 > **学习目标**：从零开始掌握 Claude Code 的安装、认证、配置，完成第一个 AI 驱动的编码项目，建立完整的日常开发工作流。 > > **适用人群**：从未使用过 Claude Code 的开发者、希望系统学习 AI 编码工具的工程师、团队技术负责人。 --- ## 一、Claude Code 是什么 Claude Code 是 Anthropic 推出的 **智能编码代理（Agentic Coding Tool）**，它不是一个简单的代码补全工具，而是一个能**读取你的代码库、编辑文件、执行命令、与 Git 和 CI/CD 集成**的全栈开发助手。它运行在你的终端中，直接理解项目上下文，无需复制粘贴代码到网页。  > *图表 1* 与传统的 AI 编码工具相比，Claude Code 的核心差异在于 **代理循环（Agentic Loop）**——它不是单轮问答，而是能自主规划、多步执行、自我修正的完整工作流。 --- ## 二、安装 Claude Code ### 2.1 系统要求 | 要求 | 最低规格 | |------|---------| | 操作系统 | macOS 12+、Ubuntu 20.04+、Windows 10+（需 WSL2） | | 内存 | 4 GB 以上 | | 网络环境 | 能访问 Anthropic API 或你的代理服务器 | | Node.js | 18+ （npm 安装方式需要；原生安装器不需要） | ### 2.2 安装方式选择（2026年最新） Claude Code 目前有 **四种** 安装方式，推荐程度从高到低排列： #### 方式一：原生安装器（推荐） 零依赖，一行命令搞定，不需要预装 Node.js 或 npm： **macOS / Linux：** ```bash curl -fsSL https://claude.ai/install.sh | sh ``` **Windows PowerShell：** ```powershell irm https://claude.ai/install.ps1 | iex ``` **macOS Homebrew：** ```bash brew install claude-code ``` **Windows WinGet：** ```powershell winget install Anthropic.ClaudeCode ``` #### 方式二：npm 安装（经典方式） 适合已有 Node.js 环境的开发者： ```bash npm install -g @anthropic-ai/claude-code ``` > **注意**：Homebrew 安装的版本不会自动更新，需手动执行 `brew upgrade claude-code`。原生安装器则支持自动更新。 #### 方式三：Linux 包管理器 ```bash # Debian/Ubuntu curl -fsSL https://claude.ai/install.sh | sh # 或通过 apt（如已添加源） sudo apt install claude-code # Fedora/RHEL sudo dnf install claude-code # Alpine sudo apk add claude-code ``` ### 2.3 验证安装 ```bash claude --version ``` 预期输出类似： ``` 2.1.56 (Claude Code) ``` 如果看到版本号，说明安装成功。如果提示 `command not found`，请检查 PATH 环境变量是否包含了安装路径。 ### 2.4 常见安装问题 | 问题 | 解决方案 | |------|---------| | `EACCES` 权限错误 | 使用 `sudo npm install -g` 或修复 npm 全局目录权限 | | 原生安装器下载慢 | 检查网络代理设置，或改用 npm 安装 | | WSL2 中无法连接 | 确保 WSL2 网络正常，检查 `/etc/resolv.conf` | | 版本过旧 | 运行 `claude update` 或 `claude install latest` 更新 | --- ## 三、认证与登录 ### 3.1 认证方式概览 Claude Code 支持多种认证方式：  > *图表 2* ### 3.2 方式一：OAuth 交互式登录（最简单） 直接运行： ```bash claude ``` 首次启动会引导你通过浏览器完成 OAuth 认证。按回车后会自动打开浏览器，登录你的 Claude 账户（Max/Pro/Team/Enterprise 订阅），授权后终端会显示登录成功。 ### 3.3 方式二：API Key 认证 如果你使用 Anthropic Console 的 API Key： ```bash export ANTHROPIC_API_KEY="sk-ant-xxxxx" claude ``` 也可以写入 shell 配置文件使其永久生效： ```bash # 添加到 ~/.bashrc 或 ~/.zshrc echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.zshrc source ~/.zshrc ``` ### 3.4 方式三：自定义 API 端点（第三方模型） 如果使用兼容 Anthropic 协议的第三方服务（如国内的智谱 GLM），在 `~/.claude/settings.json` 中配置： ```json { "env": { "ANTHROPIC_AUTH_TOKEN": "你的令牌", "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic", "ANTHROPIC_DEFAULT_SONNET_MODEL": "GLM-5.1" } } ``` ### 3.5 方式四：setup-token 命令 ```bash claude setup-token ``` 这会引导你设置一个长期有效的认证令牌，适合在 CI/CD 环境或远程服务器上使用。 ### 3.6 验证认证 登录成功后，启动 Claude Code 会看到类似提示： ``` ╭─────────────────────────────────────╮ │ Welcome to Claude Code! │ │ Model: claude-sonnet-4-6 │ │ Account: your@email.com │ ╰─────────────────────────────────────╯ > ``` --- ## 四、核心配置：CLAUDE.md `CLAUDE.md` 是 Claude Code 最重要的配置文件——它让 Claude 从一个"通用 AI"变成"**了解你项目的专属助手**"。 ### 4.1 CLAUDE.md 文件层级 Claude Code 会读取多层级的 CLAUDE.md，按优先级从低到高： ``` ~/.claude/CLAUDE.md ← 全局配置（所有项目共享） ├── 项目根目录/CLAUDE.md ← 项目级配置（推荐 git 管理） ├── 项目根目录/.claude/CLAUDE.md ← 项目级隐藏配置 └── 子目录/CLAUDE.md ← 目录级配置（特定模块） ``` ### 4.2 创建你的第一个 CLAUDE.md 在项目根目录创建： ```bash claude # 启动后输入 /init 命令自动生成 ``` 或手动创建 `CLAUDE.md`： ```markdown # 项目说明 这是一个 Node.js Express REST API 项目。 ## 技术栈 - Node.js 20 + TypeScript - Express.js - PostgreSQL + Prisma ORM - Jest 测试框架 ## 代码规范 - 使用 ESLint + Prettier - 变量名用 camelCase，文件名用 kebab-case - 每个 API 端点都有对应的集成测试 ## 重要规则 - 不要修改 prisma/migrations 目录下的迁移文件 - 所有 API 响应遵循 { success: boolean, data: any, error?: string } 格式 - 修改代码后运行 `npm test` 验证 ``` ### 4.3 CLAUDE.md 最佳实践 ```text graph TD A[CLAUDE.md 编写原则] --> B[具体而非抽象
不要说"写好代码"
要说"使用 camelCase 命名"] A --> C[包含项目上下文
技术栈、目录结构、关键文件] A --> D[明确禁止事项
不要修改哪些文件
不要引入哪些依赖] A --> E[指定验证方式
如何测试、如何构建] style A fill:#D97706,color:#fff style B fill:#3B82F6,color:#fff style C fill:#3B82F6,color:#fff style D fill:#10B981,color:#fff style E fill:#10B981,color:#fff ``` **好的 CLAUDE.md 示例**： ```markdown ## 测试命令 - 单元测试: `npm run test:unit` - E2E 测试: `npm run test:e2e` - 修改任何文件后必须运行 `npm run test:unit` 确认通过 ``` **不好的 CLAUDE.md 示例**： ```markdown ## 测试 - 记得写测试 ``` --- ## 五、交互模式与核心操作 ### 5.1 启动 Claude Code ```bash # 交互模式（最常用） cd your-project claude # 指定模型 claude --model opus # 继续上次对话 claude --continue # 恢复指定会话 claude --resume ``` ### 5.2 核心键盘快捷键 | 快捷键 | 功能 | |--------|------| | `Enter` | 发送消息 | | `Escape` | 取消当前输入 / 中断 Claude 正在执行的操作 | | `Shift + Tab` | 切换权限模式（default → acceptEdits → plan） | | `Tab` | 自动补全文件路径和命令 | | `Ctrl + C` | 中断当前操作 | | `Ctrl + D` | 退出 Claude Code | ### 5.3 权限模式详解 Claude Code 有 **6 种权限模式**，控制它在多大程度上能自主行动：  > *图表 4* | 模式 | 适用场景 | 如何启用 | |------|---------|---------| | `plan` | 需要先看方案再决定是否执行 | 启动时按 `Shift+Tab` 或 `--permission-mode plan` | | `default` | 日常开发，重要操作会询问 | 默认模式 | | `acceptEdits` | 信任 Claude 的代码编辑，只确认危险命令 | 按 `Shift+Tab` 切换 | | `dontAsk` | 信任当前项目中的所有操作 | `--permission-mode dontAsk` | | `bypassPermissions` | CI/CD 或沙盒环境 | `--dangerously-skip-permissions` | > **初学者建议**：使用 `default` 模式，Claude 在编辑文件和执行命令前都会询问你。随着信任度提升，可以切换到 `acceptEdits` 模式加快节奏。 ### 5.4 核心 Slash 命令 在交互模式中输入 `/` 开头的命令来执行特殊操作： | 命令 | 功能 | 使用场景 | |------|------|---------| | `/init` | 初始化项目 CLAUDE.md | 新项目首次使用 | | `/compact` | 压缩上下文窗口 | 对话过长、响应变慢时 | | `/clear` | 清空当前对话 | 开始新话题 | | `/model` | 切换模型 | 需要更强/更快的模型 | | `/cost` | 查看当前会话花费 | 监控 API 使用量 | | `/help` | 显示帮助信息 | 忘记命令时 | | `/memory` | 更新全局 CLAUDE.md | 记住跨项目的偏好 | | `/review` | 代码审查 | 提交 PR 前 | | `/mcp` | 管理 MCP 服务器 | 配置外部工具 | ### 5.5 非交互模式（Print 模式） 适合脚本和自动化场景： ```bash # 单次问答 claude -p "解释这个项目的主要功能" # 结合管道使用 cat error.log | claude -p "分析这个错误日志，找出根因" # 指定输出格式 claude -p "列出所有 TODO 注释" --output-format json # 限制预算 claude -p "重构这个函数" --max-budget-usd 1.0 ``` --- ## 六、settings.json 配置详解 `settings.json` 是 Claude Code 的"控制面板"，管理模型、环境变量、插件、权限等所有设置。 ### 6.1 配置文件位置 ``` ~/.claude/settings.json ← 用户级全局设置 .claude/settings.json ← 项目级设置（共享） .claude/settings.local.json ← 项目级本地设置（不提交到 git） ``` ### 6.2 关键配置项 ```json { "env": { "ANTHROPIC_API_KEY": "sk-ant-xxxxx", "ANTHROPIC_BASE_URL": "https://api.anthropic.com" }, "permissions": { "allow": [ "Bash(npm test:*)", "Bash(npm run lint:*)", "Read", "Edit" ], "deny": [ "Bash(rm -rf:*)" ] }, "enabledPlugins": { "superpowers@claude-plugins-official": true, "context7@claude-plugins-official": true }, "theme": "dark" } ``` ### 6.3 权限规则语法 权限规则使用 `工具名(参数模式)` 的格式： ```json { "permissions": { "allow": [ "Read", // 允许所有文件读取 "Edit", // 允许所有文件编辑 "Bash(git:*)", // 允许所有 git 命令 "Bash(npm test:*)", // 允许 npm test 及其子命令 "Bash(npm run lint:*)", // 允许 lint 相关命令 "WebSearch", // 允许网络搜索 "WebFetch" // 允许网页抓取 ], "deny": [ "Bash(rm -rf:*)", // 禁止 rm -rf "Bash(curl|wget *:*)", // 禁止外部下载 "Edit(.env:*)", // 禁止编辑 .env 文件 "Read(*.pem)", // 禁止读取证书文件 "Edit(*.pem)" // 禁止编辑证书文件 ] } } ``` > **安全提示**：务必在 deny 规则中保护 `.env`、`credentials`、`*.pem` 等敏感文件，防止 Claude 意外读取或修改。 --- ## 七、实战：从零创建一个完整项目 让我们用 Claude Code 从零开始创建一个 **待办事项 REST API** 项目，体验完整的 AI 驱动开发流程。 ### 7.1 项目初始化 ```bash # 创建项目目录 mkdir todo-api && cd todo-api # 初始化 Git git init # 启动 Claude Code claude ``` ### 7.2 使用 /init 初始化项目配置 在 Claude Code 交互界面中输入： ``` /init ``` Claude 会分析当前目录结构，生成一个基础 `CLAUDE.md`。然后你可以让它进一步完善： ``` 这是一个 Node.js + TypeScript + Express 的 REST API 项目， 使用 SQLite 作为数据库，Jest 作为测试框架。 请更新 CLAUDE.md 包含这些信息，并添加以下规则： - API 路由定义在 src/routes/ 目录 - 数据库模型在 src/models/ 目录 - 每个路由都要有对应的测试文件 - 修改代码后运行 npm test 验证 ``` ### 7.3 让 Claude 生成项目骨架 ``` 帮我创建这个待办事项 API 项目的完整骨架，包括： 1. package.json（含所有依赖） 2. TypeScript 配置 3. Express 主入口 src/index.ts 4. Todo 模型 src/models/todo.ts 5. CRUD 路由 src/routes/todos.ts 6. 测试文件 tests/todos.test.ts 7. ESLint + Prettier 配置 ``` Claude 会**自主完成**以下操作（在 default 模式下会逐步确认）： 1. 创建 `package.json` 并列出所有依赖 2. 创建 `tsconfig.json` 3. 编写 Express 主入口代码 4. 定义 Todo 数据模型 5. 实现 GET/POST/PUT/DELETE 四个端点 6. 编写完整的测试文件 7. 创建 lint 和 format 配置 ### 7.4 安装依赖并验证 ``` 安装依赖并运行测试 ``` Claude 会执行： ```bash npm install npm test ``` 如果测试通过，你会看到类似输出： ``` PASS tests/todos.test.ts Todo API ✓ GET /todos - 返回所有待办事项 (45 ms) ✓ POST /todos - 创建新待办事项 (23 ms) ✓ PUT /todos/:id - 更新待办事项 (18 ms) ✓ DELETE /todos/:id - 删除待办事项 (12 ms) ``` ### 7.5 迭代开发：添加新功能 ``` 给 Todo 添加一个 priority 字段（low/medium/high）， 更新模型、路由和测试 ``` Claude 会自动定位需要修改的所有文件并一次性更新——这就是 CLAUDE.md 的价值：Claude 知道你的项目结构，知道改完要跑测试。 ### 7.6 代码审查 ``` /review ``` Claude 会对当前未提交的更改进行全面的代码审查，检查潜在 bug、安全漏洞、性能问题和最佳实践违反。 ### 7.7 完整工作流总结 ```text flowchart TB S[cd your-project && claude] --> I[/init 初始化 CLAUDE.md] I --> D[描述需求给 Claude] D --> C{Claude 自主执行} C --> C1[创建/编辑文件] C --> C2[运行命令] C --> C3[执行测试] C1 --> V{验证结果} C2 --> V C3 --> V V -->|测试通过| G[git commit] V -->|有问题| F[描述问题给 Claude] F --> C G --> D style S fill:#D97706,color:#fff style C fill:#3B82F6,color:#fff style V fill:#10B981,color:#fff style G fill:#8B5CF6,color:#fff ``` --- ## 八、进阶：项目管理与上下文控制 ### 8.1 上下文窗口管理 Claude Code 有一个有限的上下文窗口。长对话会导致： - 响应变慢 - 遗忘早期信息 - API 费用增加 **管理策略**： ```bash # 压缩上下文（保留关键信息，丢弃冗余细节） /compact # 清空对话，完全重新开始 /clear # 查看当前会话消耗 /cost ``` **最佳实践**：每完成一个独立任务后执行 `/compact`，开始全新的大型任务时执行 `/clear`。 ### 8.2 多文件操作 Claude Code 天生支持跨文件操作，你只需要用自然语言描述： ``` 把 src/utils/format.ts 中的 formatDate 函数迁移到 src/utils/date.ts， 并更新所有引用它的文件 ``` Claude 会： 1. 读取 `format.ts` 找到函数 2. 在 `date.ts` 中创建新文件（或追加到已有文件） 3. 用 Grep 搜索所有引用 4. 逐一更新每个引用文件 5. 运行测试验证 ### 8.3 结合 Git 使用 ``` # 让 Claude 查看最近的改动 分析最近的 git diff，找出可能的 bug # 让 Claude 帮你写 commit 帮我提交当前的改动，commit message 用中文 # 处理合并冲突 解决当前的 git merge conflict ``` --- ## 九、常见问题与故障排除 ### 9.1 响应质量不佳 | 症状 | 原因 | 解决方案 | |------|------|---------| | Claude 不了解项目结构 | 缺少 CLAUDE.md | 运行 `/init`，补充项目信息 | | 回答偏离项目规范 | CLAUDE.md 指令不够具体 | 添加具体的代码规范和禁止事项 | | 遗忘之前的约定 | 上下文过长 | 执行 `/compact` 或 `/clear` | | 生成的代码不符合风格 | 未指定编码风格 | 在 CLAUDE.md 中添加代码风格示例 | ### 9.2 权限相关 ```bash # Claude 不断询问同一个操作？ # 在 settings.json 的 permissions.allow 中添加规则 { "permissions": { "allow": ["Bash(npm test:*)", "Bash(git:*)"] } } # 想临时提升自主度？ # 按 Shift+Tab 切换到 acceptEdits 模式 ``` ### 9.3 网络与代理 ```bash # 使用代理服务器 export HTTPS_PROXY=http://your-proxy:port claude # 使用自定义 API 端点 # 在 ~/.claude/settings.json 中配置 ANTHROPIC_BASE_URL ``` ### 9.4 性能优化 ```bash # 使用更快但成本更低的模型处理简单任务 claude --model haiku # 复杂任务使用最强模型 claude --model opus # 限制 API 花费 claude -p "快速检查" --model haiku --max-budget-usd 0.5 ``` --- ## 十、30 分钟上手路径总结 对于完全的新手，这是最高效的学习路径：  > *图表 6* --- ## 延伸阅读 - [Claude Code 官方快速入门](https://code.claude.com/docs/en/quickstart) — Anthropic 官方文档，最权威的参考 - [Claude Code 命令参考](https://code.claude.com/docs/en/commands) — 所有 Slash 命令的完整列表 - [CLAUDE.md 使用指南](https://claude.com/blog/using-claude-md-files) — Anthropic 官方博客，深入讲解项目配置 - [Claude Code 权限模式](https://code.claude.com/docs/en/permission-modes) — 安全地控制 Claude 的自主程度 - [Claude Code 工作原理](https://code.claude.com/docs/en/how-claude-code-works) — 理解代理循环和内置工具 - [Claude Code 设置参考](https://code.claude.com/docs/en/settings) — settings.json 所有配置项 - [Claude Code 认证文档](https://code.claude.com/docs/en/authentication) — API Key、OAuth、企业认证配置 --- ## 训练营适用性评估 | 维度 | 评估 | |------|------| | 适合训练营类型 | AI 编码工具入门营、开发者效率提升营、前端/后端实战营的预热模块 | | 教学时长 | 2-3 小时（含实操练习） | | 学员基础要求 | 会使用终端、了解基本 Git 操作 | | 实操占比 | 70% 实操 + 30% 讲解 | | 建议分组 | 每人独立完成，助教巡回答疑 | | 验收标准 | 学员能独立安装 Claude Code、完成认证、用 `/init` 配置项目、用自然语言完成一个 CRUD API | > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。