# Claude Code零基础入门：安装到第一个项目 ## 概述 本教程面向零基础开发者，从安装Node.js到完成第一个Claude Code项目的完整流程。你将学会：安装和配置Claude Code CLI、理解核心概念（工具、权限、会话）、编写第一个CLAUDE.md配置文件、用自然语言驱动Claude Code完成一个真实的待办事项应用。适合有基本终端操作经验、想用AI提升编码效率的所有开发者。 ## 前置条件 | 条件 | 说明 | |------|------| | 操作系统 | macOS、Linux 或 Windows (WSL2) | | Node.js | v18.0 或更高版本 | | npm | 随 Node.js 一起安装 | | 网络 | 稳定的互联网连接 | | 账户 | Anthropic账户（Pro/Max订阅）或API Key | **需要的基础知识：** - 能打开终端并输入命令 - 了解基本的Git概念（可选，但推荐） - 了解任意一门编程语言的基础语法 --- ## 第一步：安装Node.js环境 Claude Code是一个Node.js包，通过npm安装。如果你已经安装了Node.js 18+，可以跳过此步。 ### macOS安装Node.js 推荐使用 `nvm`（Node Version Manager）管理Node.js版本： ```bash # 安装nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 重新加载shell配置 source ~/.zshrc # 安装最新LTS版本的Node.js nvm install --lts # 验证安装 node --version # 应输出 v20.x.x 或更高 npm --version # 应输出 10.x.x 或更高 ``` ### Linux (Ubuntu/Debian)安装Node.js ```bash # 使用NodeSource仓库安装 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs # 验证 node --version npm --version ``` ### Windows安装Node.js Windows用户需要先启用WSL2（Windows Subsystem for Linux），然后在WSL2中按Linux方式操作： ```powershell # 在PowerShell管理员模式中安装WSL2 wsl --install # 重启后，打开Ubuntu终端，按上述Linux步骤安装Node.js ``` > **常见问题**：如果 `node --version` 显示版本低于18，请使用nvm切换到较新版本。Claude Code严格要求Node.js >= 18。 --- ## 第二步：安装Claude Code ### 通过npm全局安装 ```bash npm install -g @anthropic-ai/claude-code ``` 安装完成后验证： ```bash claude --version # 输出示例: 2.1.56 (Claude Code) ``` ### 认证登录 Claude Code支持两种认证方式： **方式一：OAuth登录（推荐，适用于Anthropic订阅用户）** ```bash claude auth ``` 执行后会自动打开浏览器，跳转到Anthropic登录页面。完成授权后，终端会显示登录成功信息。 验证登录状态： ```bash claude auth status # 输出: loggedIn: true, authMethod: oauth_token, apiProvider: firstParty ``` **方式二：API Key认证（适用于API用户）** ```bash # 设置环境变量 export ANTHROPIC_API_KEY="sk-ant-xxxxx" # 或将其添加到shell配置文件中使其永久生效 echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.zshrc source ~/.zshrc ``` > **安全提醒**：永远不要将API Key硬编码到代码中或提交到Git仓库。将 `.env` 添加到 `.gitignore`。 ### 离线Token设置（长期使用） 如果你希望避免频繁重新认证，可以设置长期Token： ```bash claude setup-token ``` 这会引导你创建一个持久化的认证Token，存储在本地配置中。 --- ## 第三步：理解Claude Code核心概念 在开始编码前，让我们先理解Claude Code的几个核心概念。这些概念将贯穿你的整个使用过程。  > *图表 1* ### 交互模式 vs 管道模式 Claude Code有两种主要运行模式： | 模式 | 命令 | 适用场景 | |------|------|----------| | 交互式 | `claude` | 日常开发、对话式编程 | | 管道模式 | `claude -p "prompt"` | 脚本集成、CI/CD、批量任务 | **交互式模式**是你的主要工作模式。启动后会进入一个对话界面，你可以用自然语言描述需求，Claude Code会自动选择合适的工具来完成任务。 **管道模式**适合自动化场景，输出结果后立即退出，可以与其他命令行工具配合使用： ```bash # 示例：让Claude Code解释当前目录的代码结构 claude -p "列出这个项目的目录结构并简要说明" # 示例：结合其他命令使用 echo "这个函数做了什么？" | claude -p ``` ### 工具系统 Claude Code内置了多种工具，它会在对话中自动选择合适的工具： - **Read**：读取文件内容 - **Edit**：精确编辑文件中的特定部分 - **Write**：创建新文件 - **Bash**：执行终端命令 - **Glob**：按模式搜索文件（如 `**/*.ts`） - **Grep**：搜索文件内容 - **Task**：启动子代理处理复杂任务 你不需要手动调用这些工具——Claude Code会根据你的自然语言描述自动选择。但了解它们的存在有助于你更好地描述需求。 ### 权限系统 Claude Code的权限系统保护你的安全。每当Claude Code想要执行敏感操作（如修改文件、运行命令），它会先请求你的确认： ``` Claude wants to edit file: src/index.ts Allow? (y/n) ``` 你可以通过配置来管理权限，减少重复确认。权限模式包括： | 模式 | 说明 | |------|------| | `default` | 默认模式，敏感操作需确认 | | `acceptEdits` | 自动接受文件编辑，命令仍需确认 | | `plan` | 只规划不执行，适合审查方案 | | `bypassPermissions` | 跳过所有权限检查（仅限沙箱环境） | --- ## 第四步：创建你的第一个项目 现在让我们用Claude Code从零开始创建一个待办事项（Todo）命令行应用。 ### 初始化项目 ```bash # 创建项目目录 mkdir my-first-claude-project cd my-first-claude-project # 初始化Git仓库 git init # 启动Claude Code claude ``` ### 编写CLAUDE.md配置文件 启动Claude Code后，首次运行它会引导你创建 `CLAUDE.md` 文件。你也可以手动创建： ```markdown # 项目：命令行待办事项应用 ## 技术栈 - 语言：Python 3 - 无需第三方依赖，仅使用标准库 - 数据存储：JSON文件 ## 编码规范 - 使用类型注解 - 函数和类添加docstring - 遵循PEP 8风格 ## 项目结构 - `todo.py` - 主程序入口 - `storage.py` - 数据存储模块 - `models.py` - 数据模型 ## 常用命令 - `python todo.py add "买菜"` - 添加任务 - `python todo.py list` - 列出所有任务 - `python todo.py done 1` - 标记任务完成 - `python todo.py delete 1` - 删除任务 ``` > **CLAUDE.md的三层配置体系**： > - `~/.claude/CLAUDE.md` — 全局配置，对所有项目生效 > - `./CLAUDE.md` — 项目配置，随项目提交到Git > - `./CLAUDE.local.md` — 本地私有配置，已添加到 `.gitignore` ### 与Claude Code对话 启动交互式会话后，输入以下提示： ``` > 请根据CLAUDE.md中的描述，创建一个命令行待办事项应用。要求： > 1. 支持添加、列表、完成、删除四个操作 > 2. 数据持久化到todos.json文件 > 3. 有清晰的终端输出格式 > 4. 包含错误处理 ``` Claude Code会自动执行以下步骤： 1. 读取CLAUDE.md理解项目需求 2. 创建 `models.py` 定义数据结构 3. 创建 `storage.py` 实现JSON读写 4. 创建 `todo.py` 实现命令行接口 5. 运行测试验证功能 **预期输出**（Claude Code会逐个创建文件）： ```python # models.py - 由Claude Code生成 from dataclasses import dataclass, field from datetime import datetime from typing import Optional @dataclass class Todo: id: int title: str completed: bool = False created_at: str = field(default_factory=lambda: datetime.now().isoformat()) completed_at: Optional[str] = None ``` ```python # storage.py - 由Claude Code生成 import json import os from typing import List from models import Todo class TodoStorage: def __init__(self, filepath: str = "todos.json"): self.filepath = filepath def load(self) -> List[Todo]: if not os.path.exists(self.filepath): return [] with open(self.filepath, "r", encoding="utf-8") as f: data = json.load(f) return [Todo(**item) for item in data] def save(self, todos: List[Todo]) -> None: with open(self.filepath, "w", encoding="utf-8") as f: json.dump([vars(t) for t in todos], f, ensure_ascii=False, indent=2) def get_next_id(self, todos: List[Todo]) -> int: return max((t.id for t in todos), default=0) + 1 ``` ```python # todo.py - 由Claude Code生成 import sys from storage import TodoStorage from models import Todo from datetime import datetime def main(): if len(sys.argv) < 2: print_usage() return storage = TodoStorage() command = sys.argv[1] if command == "add": if len(sys.argv) < 3: print("错误：请提供任务标题") return title = " ".join(sys.argv[2:]) todos = storage.load() new_todo = Todo(id=storage.get_next_id(todos), title=title) todos.append(new_todo) storage.save(todos) print(f"✓ 已添加任务 #{new_todo.id}: {title}") elif command == "list": todos = storage.load() if not todos: print("暂无任务") return for t in todos: status = "✓" if t.completed else "○" print(f" {status} #{t.id} {t.title}") elif command == "done": if len(sys.argv) < 3: print("错误：请提供任务ID") return todo_id = int(sys.argv[2]) todos = storage.load() for t in todos: if t.id == todo_id: t.completed = True t.completed_at = datetime.now().isoformat() storage.save(todos) print(f"✓ 已完成任务 #{todo_id}: {t.title}") return print(f"错误：未找到任务 #{todo_id}") elif command == "delete": if len(sys.argv) < 3: print("错误：请提供任务ID") return todo_id = int(sys.argv[2]) todos = storage.load() original_len = len(todos) todos = [t for t in todos if t.id != todo_id] if len(todos) < original_len: storage.save(todos) print(f"✓ 已删除任务 #{todo_id}") else: print(f"错误：未找到任务 #{todo_id}") else: print(f"未知命令: {command}") print_usage() def print_usage(): print("用法: python todo.py <命令> [参数]") print("命令:") print(" add <标题> 添加新任务") print(" list 列出所有任务") print(" done 标记任务完成") print(" delete 删除任务") if __name__ == "__main__": main() ``` ### 测试应用 让Claude Code帮你测试，或手动运行： ```bash python todo.py add "学习Claude Code" # ✓ 已添加任务 #1: 学习Claude Code python todo.py add "写CLAUDE.md配置" # ✓ 已添加任务 #2: 写CLAUDE.md配置 python todo.py list # ○ #1 学习Claude Code # ○ #2 写CLAUDE.md配置 python todo.py done 1 # ✓ 已完成任务 #1: 学习Claude Code python todo.py list # ✓ #1 学习Claude Code # ○ #2 写CLAUDE.md配置 python todo.py delete 2 # ✓ 已删除任务 #2 ``` --- ## 第五步：掌握常用命令和工作流 完成第一个项目后，让我们系统学习Claude Code的日常使用命令。 ### 启动与退出 ```bash # 启动交互式会话（在项目目录中） claude # 继续上次的对话 claude -c # 恢复特定会话（按ID或搜索） claude -r "todo" # 退出会话 # 按 Ctrl+C 两次，或输入 /exit ``` ### 交互式会话中的斜杠命令 在Claude Code交互式会话中，你可以使用以下内置斜杠命令： | 命令 | 功能 | |------|------| | `/help` | 显示帮助信息 | | `/clear` | 清除当前对话历史 | | `/compact` | 压缩对话历史以释放上下文空间 | | `/permissions` | 查看和管理工具权限 | | `/model` | 切换模型（如从sonnet切换到opus） | | `/exit` | 退出Claude Code | | `/review` | 让Claude Code审查你的代码变更 | | `/init` | 重新初始化CLAUDE.md | ### 模型选择 ```bash # 在启动时指定模型 claude --model sonnet # 快速高效 claude --model opus # 最强推理能力 # 在会话中切换 > /model # 会显示可用模型列表供选择 ``` ### Effort级别控制 Claude Code支持控制"努力程度"，影响回答的深度和长度： ```bash # 低努力 - 快速回答，适合简单问题 claude --effort low # 中等努力 - 平衡模式（默认） claude --effort medium # 高努力 - 深度思考，适合复杂任务 claude --effort high ``` --- ## 第六步：配置和定制 ### settings.json详解 Claude Code的配置文件位于 `~/.claude/settings.json`，支持以下主要配置： ```json { "env": { "ANTHROPIC_API_KEY": "your-api-key" }, "permissions": { "allow": [ "Bash(python:*)", "Bash(git:*)", "Read", "Edit" ], "deny": [ "Bash(rm -rf:*)" ] }, "theme": "dark", "verbose": false } ``` ### 权限配置实战 减少重复确认是提升Claude Code使用效率的关键。在项目根目录创建 `.claude/settings.json`： ```json { "permissions": { "allow": [ "Bash(python:*)", "Bash(pytest:*)", "Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)", "Read", "Edit", "Glob", "Grep" ], "deny": [ "Bash(rm -rf:*)", "Bash(sudo:*)" ] } } ``` > **安全原则**：只允许你信任的操作。`Bash(python:*)` 允许所有以 `python` 开头的命令，但 `Bash(rm -rf:*)` 明确禁止危险操作。 ### Plan模式：先规划后执行 当你面对复杂任务时，建议先进入Plan模式： ```bash # 启动时使用plan模式 claude --permission-mode plan # 或在会话中让Claude Code先规划 > 请先规划一下如何重构这个应用，不要直接修改代码 ``` Plan模式下Claude Code只会分析和规划，不会执行任何文件修改或命令运行。确认方案后再切换回正常模式执行。  > *图表 2* --- ## 第七步：Git集成工作流 Claude Code与Git深度集成，让版本控制变得轻松。 ### 常见Git工作流 ```bash # 让Claude Code查看当前状态 > 查看当前的git状态和最近的改动 # 让Claude Code帮你提交 > 请帮我提交当前的改动，写一个清晰的commit message # 代码审查 > /review # Claude Code会分析所有未提交的改动并给出建议 # 创建分支 > 请创建一个feature/add-search分支，并切换过去 ``` ### Worktree：并行开发利器 当你需要同时处理多个任务时，Worktree功能让你在不同分支上并行工作： ```bash # 在新的worktree中启动Claude Code claude --worktree feature-add-search # 这会自动创建一个新的git worktree和分支 # Claude Code在其中独立工作，不会影响主分支 # 完成后，回到主目录合并 git merge feature-add-search ``` --- ## 实战案例：构建带搜索功能的增强版Todo应用 让我们在刚才的基础上增强Todo应用，体验完整的Claude Code开发工作流。 ### Step 1：描述需求 ``` > 请在现有Todo应用基础上添加以下功能： > 1. 搜索功能 - 支持按标题关键词搜索 > 2. 优先级 - 支持设置高/中/低优先级，列表按优先级排序 > 3. 标签系统 - 支持给任务添加标签，按标签筛选 > 4. 彩色输出 - 使用ANSI颜色码美化终端输出 ``` ### Step 2：审查Claude Code的方案 Claude Code会先分析现有代码，然后给出修改方案。审查时注意： - 改动是否影响现有功能 - 数据迁移是否需要（JSON格式变化） - 新增依赖是否合理 ### Step 3：迭代优化 ``` > 搜索功能还需要支持模糊匹配，比如"claude"能匹配到"学习Claude Code" > > 另外，添加任务时如果没有指定优先级，默认为"中" ``` ### Step 4：测试和提交 ``` > 请运行以下测试：添加5个不同优先级的任务，搜索其中一个，完成一个，删除一个，然后列出所有任务 > 确认功能正常后，帮我提交代码 ``` --- ## 常见问题与解决方案 ### 问题1：安装失败 - 权限错误 ```bash # 错误信息 npm ERR! Error: EACCES: permission denied # 解决方案：不要使用sudo安装npm包，改用nvm管理Node.js npm install -g @anthropic-ai/claude-code ``` ### 问题2：登录后仍提示未认证 ```bash # 检查认证状态 claude auth status # 重新登录 claude auth # 如果使用API Key，检查环境变量 echo $ANTHROPIC_API_KEY ``` ### 问题3：上下文窗口不足 当项目很大或对话很长时，可能遇到上下文窗口不足： ``` # 在会话中使用 /compact 压缩历史 > /compact # 或启动新会话但保留项目上下文 > /clear # 使用 --add-dir 添加额外目录 claude --add-dir ../shared-lib ``` ### 问题4：Claude Code执行了不想执行的操作 Claude Code有完善的撤销机制： 1. **文件修改**：使用 `git diff` 查看变更，`git checkout -- ` 撤销 2. **误删文件**：`git checkout -- ` 恢复 3. **命令执行**：权限系统默认保护你，敏感操作需要确认 > **最佳实践**：频繁使用 `git commit`。每次Claude Code完成一个有意义的改动后，手动提交，这样总有回退点。 ### 问题5：回答速度慢 ```bash # 使用更快的模型 claude --model sonnet # 使用fast模式（同模型更快输出） # 在会话中输入 /fast # 降低effort级别 claude --effort low ``` --- ## 完整工作流总结  > *图表 3* --- ## 进阶技巧速览 | 技巧 | 命令/操作 | 场景 | |------|-----------|------| | 快速提问 | `claude -p "问题"` | 不需要上下文的快速问答 | | 继续上次对话 | `claude -c` | 中断后继续工作 | | 指定上下文文件 | 在CLAUDE.md中说明 | 让Claude理解项目结构 | | 多目录支持 | `claude --add-dir ../lib` | 跨目录引用代码 | | 结构化输出 | `claude -p --output-format json` | 脚本集成 | | 费用控制 | `claude -p --max-budget-usd 0.5` | 限制单次会话花费 | | 自定义系统提示 | `claude --system-prompt "你是Python专家"` | 专业化角色设定 | | 会话恢复 | `claude -r "关键词"` | 找回历史会话 | --- ## 延伸阅读 - [Claude Code官方文档](https://code.claude.com/docs/en/quickstart) — 完整的官方快速入门指南 - [Claude Code命令参考](https://code.claude.com/docs/en/commands) — 所有斜杠命令和CLI标志 - [Claude Code权限配置](https://code.claude.com/docs/en/permissions) — 详细的权限管理文档 - [Claude Code高级设置](https://code.claude.com/docs/en/setup) — 平台特定安装和版本管理 - [Claude Code GitHub](https://github.com/anthropics/claude-code) — 源代码和Issue追踪 - [Claude Code Cheat Sheet](https://computingforgeeks.com/claude-code-cheat-sheet/) — 2026年速查表 - [45 Claude Code Tips](https://github.com/ykdojo/claude-code-tips) — 从基础到高级的技巧合集 --- ## 训练营适用性评估 | 维度 | 评估 | |------|------| | 适合训练营类型 | AI编程入门训练营、全栈开发训练营、DevOps效率训练营 | | 学员基础要求 | 基本终端操作能力，了解任意一门编程语言 | | 预计教学时长 | 2-3小时（含动手实践） | | 实验环境要求 | 每人一台有网络的电脑，预装Node.js 18+ | | 建议分组方式 | 2人一组，一人操作一人记录，交替进行 | | 考核方式 | 独立完成一个CLI小工具（如计算器、日记本、密码生成器） | | 后续课程衔接 | Round 2: Claude Code Skills开发实战 | > [!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 等场景全覆盖。