# Claude Code从零开始：安装、配置与第一个项目 ## 概述 本教程面向零基础用户，系统讲解如何从安装 Claude Code 到完成第一个真实项目的全流程。你将学会在终端中安装 Claude Code、完成身份认证、编写 CLAUDE.md 项目配置、掌握核心交互命令，并独立构建一个可运行的 Web 应用。无论你是后端工程师、前端开发者还是 DevOps 运维人员，本教程都能帮助你快速将 Claude Code 融入日常开发工作流。 **适用人群**：有基本终端操作经验的开发者，无需 AI 编程工具使用基础。 --- ## 一、Claude Code 是什么 Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手。它运行在你的终端中，能够： - **读取和编辑文件**：理解整个代码仓库的上下文 - **执行 Shell 命令**：运行测试、安装依赖、启动服务 - **搜索代码库**：快速定位函数定义、追踪调用链 - **管理 Git 操作**：提交代码、创建分支、发起 PR - **通过对话构建功能**：用自然语言描述需求，Claude Code 帮你实现 与传统的 IDE 插件不同，Claude Code 不是一个代码补全工具——它是一个完整的 AI Agent，拥有工具调用能力，能自主规划任务步骤并逐步执行。  > *图表 1* --- ## 二、环境准备与安装 ### 2.1 系统要求 | 组件 | 最低要求 | 推荐配置 | |------|----------|----------| | 操作系统 | macOS 12+、Ubuntu 20.04+、Windows 10+（WSL2） | 最新 LTS 版本 | | Node.js | 18.0 及以上 | 20.x LTS | | 内存 | 4 GB RAM | 8 GB+ RAM | | 网络 | 能访问 Anthropic API | 稳定国际网络连接 | ### 2.2 安装方式 截至 2026 年 5 月，Claude Code 支持两种安装方式： #### 方式一：原生安装器（推荐） 2026 年新增的原生安装器不再依赖 Node.js，安装更轻量： **macOS（Homebrew）**： ```bash brew install claude-code ``` **Linux（apt）**： ```bash curl -fsSL https://claude.ai/install.sh | sh ``` **Windows（PowerShell）**： ```powershell winget install Anthropic.ClaudeCode ``` #### 方式二：npm 安装（传统方式） 如果你的环境已有 Node.js，仍可通过 npm 安装： ```bash npm install -g @anthropic-ai/claude-code ``` > **注意**：npm 安装方式虽然仍然可用，但 Anthropic 已将原生安装器作为推荐方式。如果你使用 Node.js 版本管理器（如 nvm），npm 方式可能会在切换 Node 版本后失效。 ### 2.3 验证安装 安装完成后，验证是否成功： ```bash claude --version ``` 预期输出类似： ``` Claude Code v1.0.x ``` 如果提示 `command not found`，请检查： - npm 全局安装路径是否在 `$PATH` 中 - 是否需要重启终端 - 是否正确安装了 Node.js 18+ --- ## 三、身份认证 ### 3.1 启动认证流程 首次运行 Claude Code 会自动引导认证： ```bash claude ``` 系统会提示两种认证方式： **方式一：Anthropic API Key** 适合有 Anthropic 账户的开发者。在 [console.anthropic.com](https://console.anthropic.com) 获取 API Key 后： ```bash # 方式 A：通过环境变量（推荐，适合 CI/CD） export ANTHROPIC_API_KEY="sk-ant-xxxxx" claude # 方式 B：通过交互式登录 claude # 按提示选择 "API Key" 并粘贴密钥 ``` **方式二：Claude Max 订阅** 如果你有 Claude Max（原 Claude Pro/Team）订阅，直接通过浏览器 OAuth 登录即可： ```bash claude # 选择 "Claude Max / Claude Team" 登录 # 浏览器自动弹出 OAuth 页面 # 授权后终端自动完成认证 ``` ### 3.2 验证认证状态 ```bash claude auth status ``` 认证成功后会显示你的账户类型和 API 额度信息。 ### 3.3 常见认证问题 | 问题 | 原因 | 解决方案 | |------|------|----------| | `Authentication failed` | API Key 无效或过期 | 重新生成 Key | | `Rate limit exceeded` | API 调用频率超限 | 等待限制重置或升级计划 | | OAuth 页面打不开 | 网络代理问题 | 检查代理设置或使用 API Key 方式 | | `Node version mismatch` | Node.js 版本过低 | 升级到 Node.js 18+ | --- ## 四、核心概念与交互模式 ### 4.1 三种交互模式 Claude Code 提供三种使用模式，适应不同场景：  > *图表 2* **交互模式**（最常用）： ```bash claude ``` 进入交互式对话界面，可以持续多轮对话，Claude Code 会记住上下文。 **单次模式**（适合脚本化）： ```bash claude -p "解释 src/utils.ts 中 formatDate 函数的逻辑" ``` 执行完一条指令后自动退出。 **管道模式**（适合批量处理）： ```bash cat error.log | claude -p "分析这些错误日志，找出根本原因" ``` 将其他命令的输出作为输入传给 Claude Code。 ### 4.2 常用斜杠命令 在交互模式中，使用 `/` 开头的斜杠命令可以快速执行操作： | 命令 | 功能 | 示例场景 | |------|------|----------| | `/help` | 查看帮助信息 | 忘记命令时 | | `/clear` | 清空对话上下文 | 开始新话题 | | `/compact` | 压缩上下文 | 对话过长时节省 token | | `/model` | 切换模型 | 在 Opus/Sonnet/Haiku 间切换 | | `/cost` | 查看当前会话费用 | 控制成本 | | `/status` | 查看上下文状态 | 了解当前加载了哪些文件 | | `/review` | 代码审查 | 提交 PR 前检查 | | `/init` | 初始化 CLAUDE.md | 新项目首次使用 | ### 4.3 权限系统 Claude Code 采用分层的权限控制，保护你的系统安全：  > *图表 3* - **自动允许**：读取文件、搜索代码等只读操作 - **需要确认**：编辑文件、执行 Shell 命令（首次会弹出确认） - **始终拒绝**：涉及敏感数据的危险操作 你可以通过 `y` 键一次性允许，或选择 "Always allow" 让特定操作自动通过。 --- ## 五、配置你的第一个项目 ### 5.1 创建项目目录 ```bash mkdir my-first-claude-project cd my-first-claude-project git init ``` ### 5.2 初始化 CLAUDE.md CLAUDE.md 是 Claude Code 的项目配置文件，告诉 AI 你的项目规则、偏好和约束： ```bash claude # 在交互模式中输入： > /init ``` Claude Code 会分析你的项目结构，自动生成一个初始的 CLAUDE.md 文件。你也可以手动创建： ```markdown # 项目：个人任务管理器 ## 技术栈 - Node.js + Express 后端 - SQLite 数据库 - 原生 HTML/CSS/JS 前端 ## 编码规范 - 使用中文注释 - 函数名使用 camelCase - 文件名使用 kebab-case - 错误处理使用 try-catch ## 项目结构 - server.js：入口文件 - routes/：API 路由 - public/：静态前端文件 - db/：数据库相关 ## 注意事项 - 不要删除现有数据库文件 - 新增 API 需要写对应的测试 - 提交前确保 npm test 通过 ``` ### 5.3 CLAUDE.md 的分层配置 Claude Code 支持三个层级的配置文件：  > *图表 4* - **全局配置**（`~/.claude/CLAUDE.md`）：你的个人偏好，如语言、编码风格 - **项目配置**（项目根目录 `CLAUDE.md`）：项目规则，可提交到 Git 供团队共享 - **局部配置**（子目录中的 `.claude/CLAUDE.md`）：特定模块的规则 这种分层设计意味着你可以在全局配置中设定中文回复偏好，在项目配置中设定具体技术栈约束，两者自动合并生效。 ### 5.4 settings.json 高级配置 除了 CLAUDE.md，你还可以通过 `settings.json` 进行更精细的控制： **全局配置**（`~/.claude/settings.json`）： ```json { "permissions": { "allow": [ "Bash(npm test)", "Bash(npm run *)", "Read", "Glob", "Grep" ], "deny": [ "Bash(rm -rf *)" ] } } ``` **项目配置**（`.claude/settings.json`）： ```json { "permissions": { "allow": [ "Bash(python manage.py test)", "Bash(python manage.py runserver)" ] }, "hooks": { "PostToolUse": [ { "command": "echo '工具调用完成'" } ] } } ``` --- ## 六、实战：用 Claude Code 构建一个任务管理器 让我们用一个完整的实战案例，体验 Claude Code 的完整工作流。 ### 6.1 需求描述 构建一个命令行任务管理器，功能包括： - 添加任务（标题 + 优先级） - 列出所有任务 - 标记任务完成 - 删除任务 - 数据持久化（JSON 文件） ### 6.2 启动 Claude Code 并描述需求 ```bash cd my-first-claude-project claude ``` 在交互模式中输入： ``` 请用 Node.js 创建一个命令行任务管理器。要求： 1. 支持 add/list/complete/delete 四个命令 2. 任务有标题、优先级（高/中/低）、创建时间、完成状态 3. 数据保存到 tasks.json 文件 4. 使用中文界面 5. 包含完整的错误处理 ``` ### 6.3 预期交互过程 Claude Code 会自主规划任务并逐步执行： ``` 🤖 Claude Code 规划： 1. 创建 package.json 和项目结构 2. 编写核心 task-manager.js 模块 3. 编写 CLI 入口 index.js 4. 添加错误处理和数据持久化 5. 测试所有命令 Claude Code 正在执行： 📄 创建 package.json 📄 创建 src/task-manager.js 📄 创建 src/cli.js 📄 创建 index.js 🔧 运行 npm init -y ✅ 项目初始化完成 ``` ### 6.4 生成的核心代码示例 Claude Code 会生成类似以下的代码： **src/task-manager.js**： ```javascript const fs = require('fs'); const path = require('path'); const DATA_FILE = path.join(__dirname, '..', 'tasks.json'); function loadTasks() { try { if (fs.existsSync(DATA_FILE)) { const data = fs.readFileSync(DATA_FILE, 'utf-8'); return JSON.parse(data); } } catch (err) { console.error('读取任务数据失败:', err.message); } return []; } function saveTasks(tasks) { try { fs.writeFileSync(DATA_FILE, JSON.stringify(tasks, null, 2), 'utf-8'); } catch (err) { console.error('保存任务数据失败:', err.message); } } function addTask(title, priority = '中') { const tasks = loadTasks(); const task = { id: Date.now(), title, priority, completed: false, createdAt: new Date().toLocaleString('zh-CN') }; tasks.push(task); saveTasks(tasks); console.log(`✅ 任务已添加: ${title} [${priority}]`); } function listTasks() { const tasks = loadTasks(); if (tasks.length === 0) { console.log('📋 暂无任务'); return; } console.log('📋 任务列表:'); tasks.forEach(t => { const status = t.completed ? '✅' : '⬜'; console.log(` ${status} [${t.id}] ${t.title} (${t.priority}) - ${t.createdAt}`); }); } function completeTask(id) { const tasks = loadTasks(); const task = tasks.find(t => t.id === Number(id)); if (!task) { console.log('❌ 未找到该任务'); return; } task.completed = true; saveTasks(tasks); console.log(`✅ 任务已完成: ${task.title}`); } function deleteTask(id) { let tasks = loadTasks(); const len = tasks.length; tasks = tasks.filter(t => t.id !== Number(id)); if (tasks.length === len) { console.log('❌ 未找到该任务'); return; } saveTasks(tasks); console.log(`🗑️ 任务已删除`); } module.exports = { addTask, listTasks, completeTask, deleteTask }; ``` ### 6.5 测试运行 在 Claude Code 中继续对话： ``` 帮我测试一下所有功能 ``` Claude Code 会执行以下命令验证： ```bash node index.js add "学习 Claude Code" 高 node index.js add "完成项目文档" 中 node index.js add "代码审查" 低 node index.js list node index.js complete 1 node index.js list node index.js delete 2 node index.js list ``` 预期输出： ``` ✅ 任务已添加: 学习 Claude Code [高] ✅ 任务已添加: 完成项目文档 [中] ✅ 任务已添加: 代码审查 [低] 📋 任务列表: ⬜ [1716...] 学习 Claude Code (高) - 2026/5/18 10:30:00 ⬜ [1716...] 完成项目文档 (中) - 2026/5/18 10:30:01 ⬜ [1716...] 代码审查 (低) - 2026/5/18 10:30:02 ✅ 任务已完成: 学习 Claude Code 📋 任务列表: ✅ [1716...] 学习 Claude Code (高) - 2026/5/18 10:30:00 ⬜ [1716...] 完成项目文档 (中) - 2026/5/18 10:30:01 ⬜ [1716...] 代码审查 (低) - 2026/5/18 10:30:02 🗑️ 任务已删除 📋 任务列表: ✅ [1716...] 学习 Claude Code (高) - 2026/5/18 10:30:00 ⬜ [1716...] 代码审查 (低) - 2026/5/18 10:30:02 ``` ### 6.6 完整工作流程图  > *图表 5* --- ## 七、核心工具详解 Claude Code 内置了丰富的工具集，理解这些工具能帮助你更高效地使用它： ### 7.1 文件操作工具 | 工具 | 用途 | 触发场景 | |------|------|----------| | **Read** | 读取文件内容 | "看一下 config.js" | | **Edit** | 精确编辑文件指定行 | "把第 10 行改成..." | | **Write** | 创建新文件 | "创建一个 utils.js" | | **Glob** | 按模式搜索文件名 | "找到所有 .test.js 文件" | | **Grep** | 搜索文件内容 | "找到所有使用 useState 的地方" | ### 7.2 执行工具 | 工具 | 用途 | 触发场景 | |------|------|----------| | **Bash** | 执行 Shell 命令 | "运行测试"、"安装依赖" | | **WebSearch** | 搜索互联网 | "查一下最新的 Express 文档" | | **WebFetch** | 抓取网页内容 | "看一下这个 API 文档" | ### 7.3 任务管理工具 | 工具 | 用途 | 触发场景 | |------|------|----------| | **TodoWrite** | 管理任务列表 | 复杂多步骤任务自动创建 | | **Task** | 启动子代理 | 并行处理独立子任务 | --- ## 八、高效使用技巧 ### 8.1 提示词最佳实践 Claude Code 对提示词的质量非常敏感。以下是写出高效提示词的几个原则： **原则一：明确上下文** ``` ❌ 不好：修一下那个 bug ✅ 好：修复 src/api/auth.js 中 login 函数的 token 过期判断逻辑， 当 refreshToken 为 null 时会抛出 TypeError ``` **原则二：分步骤描述复杂任务** ``` 请帮我完成以下步骤： 1. 在 src/models/ 下创建 Task 模型 2. 在 src/routes/ 下创建 tasks 路由 3. 在 server.js 中注册路由 4. 添加对应的单元测试 ``` **原则三：利用 CLAUDE.md 持久化常用指令** 把重复的指令写入 CLAUDE.md，避免每次手动输入： ```markdown ## 开发规则 - 新增 API 端点时自动添加 JSDoc 注释 - 所有数据库操作使用事务 - 提交前运行 npm run lint 修复格式问题 ``` ### 8.2 上下文管理 Claude Code 的上下文窗口有限。当对话过长时，使用以下策略：  > *图表 6* - `/compact`：智能压缩历史对话，保留关键信息 - `/clear`：完全清空上下文，适合切换话题 - 及时关闭不再相关的文件讨论 ### 8.3 模型选择策略 Claude Code 支持在多个模型间切换，不同场景推荐不同模型： | 模型 | 适用场景 | 特点 | |------|----------|------| | **Claude Opus** | 复杂架构设计、大型重构 | 最强推理能力，速度较慢 | | **Claude Sonnet** | 日常编码、Bug 修复 | 性能与速度的平衡 | | **Claude Haiku** | 快速问答、简单修改 | 速度最快，成本最低 | 使用 `/model` 命令可在会话中随时切换。 ### 8.4 成本控制 - 使用 `/cost` 实时查看 token 消耗 - 简单任务用 Haiku，复杂任务用 Opus - 利用 `/compact` 避免上下文无限膨胀 - 单次任务用 `-p` 模式，避免交互模式的额外开销 --- ## 九、与 Git 工作流集成 Claude Code 天然支持 Git 操作，能大幅提升版本控制效率： ### 9.1 常用 Git 场景 ```bash # 让 Claude Code 分析改动并生成 commit message claude -p "分析 git diff，生成合适的 commit message" # 让 Claude Code 帮你创建分支和 PR claude > 请基于当前改动创建一个新分支 feature/task-priority， > 提交代码，并发起 Pull Request ``` ### 9.2 代码审查 ``` # 交互模式中 > /review # 或直接描述需求 > 审查 src/api/ 目录下的所有文件，检查是否有 SQL 注入风险 ``` --- ## 十、MCP 服务器与 Skills 简介 作为入门教程的最后一部分，简要介绍 Claude Code 的两大扩展机制： ### 10.1 MCP（Model Context Protocol）服务器 MCP 服务器让 Claude Code 能连接外部工具和数据源： ```json // .claude/settings.json { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@anthropic-ai/mcp-filesystem", "/path/to/project"] } } } ``` 常见 MCP 服务器包括： - **filesystem**：扩展文件系统访问 - **github**：直接操作 GitHub Issues/PR - **postgres**：查询数据库 - **browser**：浏览器自动化 ### 10.2 Skills（技能系统） Skills 是 Claude Code 的可复用知识模块，可扩展其专业能力： ```bash # 查看可用 Skills claude skills list # 使用内置 Skill claude -p "/commit" # 智能 commit claude -p "/review-pr" # PR 审查 ``` 你可以从社区安装 Skills，也可以自己开发。后续教程将详细讲解 Skills 开发。  > *图表 7* --- ## 十一、常见问题与故障排除 ### 11.1 安装问题 | 问题 | 解决方案 | |------|----------| | `EACCES: permission denied` | 使用 `sudo npm install -g` 或修复 npm 权限 | | `node: command not found` | 安装 Node.js 或检查 PATH 配置 | | 安装后 `claude` 命令不可用 | 检查 npm 全局路径：`npm config get prefix` | | Windows WSL 中路径问题 | 确保在 WSL 内安装 Node.js，而非使用 Windows 版本 | ### 11.2 运行时问题 | 问题 | 解决方案 | |------|----------| | 响应变慢或超时 | 检查网络连接，尝试切换模型 | | 上下文丢失 | 使用 `/compact` 而非 `/clear` | | 文件读取失败 | 检查文件权限和路径 | | 命令执行被拒绝 | 检查 settings.json 中的权限配置 | ### 11.3 性能优化清单 - 保持 CLAUDE.md 简洁（控制在 100 行以内） - 大型项目在 `.claude/CLAUDE.md` 中指定关键目录 - 用 `.gitignore` 排除不需要的文件 - 善用 `Glob` 和 `Grep` 替代全仓库扫描 - 定期 `/compact` 控制上下文大小 --- ## 十二、延伸阅读 - **官方文档**：[code.claude.com/docs](https://code.claude.com/docs/en/quickstart) — 最权威的参考 - **Anthropic GitHub**：[github.com/anthropics/claude-code](https://github.com/anthropics/claude-code) — 源码和 Issue 追踪 - **DeepWiki 解析**：[deepwiki.com/anthropics/claude-code](https://deepwiki.com/anthropics/claude-code) — 架构深度解析 - **Claude Code Tips**：[github.com/ykdojo/claude-code-tips](https://github.com/ykdojo/claude-code-tips) — 45 条实用技巧 - **Builder.io 指南**：[builder.io/blog/claude-code-tips-best-practices](https://www.builder.io/blog/claude-code-tips-best-practices) — 50 条最佳实践 --- ## 训练营适用性评估 | 评估维度 | 说明 | |----------|------| | **适合训练营类型** | AI 编程工具入门训练营、全栈开发训练营、DevOps 效率提升训练营 | | **预计教学时长** | 2-3 小时（含实操环节） | | **学员基础要求** | 基本的终端/命令行操作能力，了解任意一门编程语言 | | **实操占比** | 60% 实操 + 40% 讲解 | | **硬件要求** | 每人一台笔记本（macOS/Linux/Windows WSL），需联网 | | **考核方式** | 独立使用 Claude Code 完成一个 Mini 项目（如任务管理器），演示功能完整性 | > [!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 等场景全覆盖。