# Claude Code零基础入门到实战：安装、配置与第一个项目 ## 概述 本教程面向从未接触过 Claude Code 的开发者，从零开始讲解安装、认证、项目配置到完成第一个真实编码任务的完整流程。学完本教程后，你将能够在自己的终端中独立使用 Claude Code 进行代码生成、调试、重构和 Git 操作，并理解 CLAUDE.md、Skills、MCP 等核心扩展机制的定位与使用时机。 **适用人群**：有一定编程基础（会使用终端/命令行）、但从未使用过 Claude Code 的开发者。 **学习目标**： 1. 独立完成 Claude Code 的安装与认证 2. 理解 `.claude` 目录结构与配置层级 3. 编写自己的 CLAUDE.md 项目指令文件 4. 完成一个包含代码生成、调试、Git 提交的完整实战项目 --- ## 一、Claude Code 是什么 Claude Code 是 Anthropic 推出的官方命令行工具（CLI），将 Claude AI 直接嵌入你的终端环境。与网页版 Claude 不同，Claude Code 具备以下独特能力： - **文件系统访问**：直接读写你本地项目中的文件 - **终端命令执行**：运行构建、测试、部署等任意 Shell 命令 - **代码库索引**：自动理解整个项目的代码结构和依赖关系 - **Git 深度集成**：创建提交、解决冲突、发起 Pull Request - **多文件编辑**：一次任务中修改多个文件，保持项目级一致性 - **扩展生态**：通过 Skills、MCP、Hooks、Plugins 无限扩展能力 用一张图理解 Claude Code 的核心架构：  > *图表 1* --- ## 二、安装前置条件 ### 2.1 系统要求 | 要求 | 最低规格 | |------|---------| | 操作系统 | macOS 12+、Ubuntu 20.04+、Windows 10/11（WSL2） | | Node.js | 18.0 或更高版本 | | 内存 | 至少 4GB RAM | | 网络 | 稳定的互联网连接 | | 账户 | Claude Pro/Max/Team/Enterprise 订阅，或 API Key | ### 2.2 检查 Node.js 环境 Claude Code 依赖 Node.js 运行时。打开终端，执行： ```bash node --version # 预期输出类似：v20.11.0 或更高 ``` 如果未安装 Node.js 或版本低于 18，推荐使用 `nvm`（Node Version Manager）安装： ```bash # 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 或 source ~/.zshrc # 安装 Node.js LTS 版本 nvm install --lts nvm use --lts # 验证 node --version npm --version ``` > **Windows 用户注意**：Claude Code 在 Windows 上需要通过 WSL2（Windows Subsystem for Linux）运行。如果你的 Windows 未安装 WSL，请先执行 `wsl --install` 并重启。 --- ## 三、安装 Claude Code ### 3.1 推荐安装方式：原生安装脚本（Native Install） 这是 Anthropic 官方推荐的最简安装方式，支持自动更新： **macOS / Linux / WSL：** ```bash curl -fsSL https://claude.ai/install.sh | bash ``` **Windows PowerShell：** ```powershell irm https://claude.ai/install.ps1 | iex ``` **Windows CMD：** ```cmd curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd ``` 原生安装的优势是**自动后台更新**，无需手动维护版本。 ### 3.2 备选安装方式 **通过 npm 安装（经典方式）：** ```bash npm install -g @anthropic-ai/claude-code ``` **通过 Homebrew 安装（macOS）：** ```bash # 稳定版（约滞后一周） brew install --cask claude-code # 最新版 brew install --cask claude-code@latest ``` > Homebrew 安装**不会自动更新**，需手动执行 `brew upgrade claude-code`。 **通过 WinGet 安装（Windows）：** ```powershell winget install Anthropic.ClaudeCode ``` ### 3.3 验证安装 ```bash claude --version # 预期输出：2.1.56 (Claude Code) 或更高版本号 ``` 查看完整命令列表： ```bash claude --help ``` **安装失败的常见排查**： | 问题 | 原因 | 解决方案 | |------|------|---------| | `command not found: claude` | PATH 未包含安装路径 | 重启终端，或执行 `source ~/.bashrc` | | `EACCES: permission denied` | npm 全局目录权限不足 | 使用 `nvm` 管理 Node.js，或 `sudo npm install -g` | | Node.js 版本过低 | 版本 < 18 | 升级 Node.js 到 18+ | | 网络超时 | 防火墙/代理 | 配置 HTTP 代理或使用镜像源 | --- ## 四、认证与登录 ### 4.1 首次启动 在终端中进入任意项目目录，执行： ```bash claude ``` 首次运行将看到登录提示。Claude Code 支持多种认证方式：  > *图表 2* ### 4.2 推荐认证流程（Claude 订阅用户） 1. 执行 `claude` 启动交互式会话 2. 选择 "Claude Pro/Max/Team/Enterprise" 3. 浏览器自动打开 Anthropic 登录页面 4. 登录并授权后，终端自动完成认证 5. 凭证将保存在本地，后续无需重复登录 ### 4.3 API Key 认证（开发者） 如果你使用 API Key 直接访问： ```bash export ANTHROPIC_API_KEY="sk-ant-xxxxx" claude ``` 或将 Key 永久写入 Shell 配置： ```bash echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.bashrc source ~/.bashrc ``` ### 4.4 切换账户 在 Claude Code 交互式会话中，使用 `/login` 命令切换账户： ``` > /login # 按提示选择新的认证方式 ``` ### 4.5 验证认证状态 ```bash claude auth status 2>/dev/null || claude --version ``` --- ## 五、理解配置体系 Claude Code 的配置系统是多层的，理解层级关系是高效使用的关键。 ### 5.1 配置层级图 ```text graph TB subgraph 全局级 "~/.claude/" A["CLAUDE.md
全局指令（所有项目生效）"] B["settings.json
全局设置"] C["skills/
全局 Skills"] end subgraph 项目级 "项目根/.claude/" D["CLAUDE.md
项目指令（仅本项目）"] E["settings.json
项目设置"] F["commands/
项目自定义命令"] end subgraph 本地级 "项目根/.claude/local/" G["settings.local.json
本地覆盖（不提交Git）"] end subgraph 根目录 "项目根/" H["CLAUDE.md
根目录指令（最简配置）"] end A -.->|优先级从高到低| H G -->|覆盖| E E -->|覆盖| B style A fill:#f96,stroke:#333 style D fill:#9cf,stroke:#333 style H fill:#9f9,stroke:#333 ``` ### 5.2 CLAUDE.md：你的项目说明书 CLAUDE.md 是 Claude Code 最重要的配置文件。它告诉 Claude 你的项目规范、编码偏好、技术栈等信息。Claude 在每次会话开始时都会读取这个文件。 **三种放置位置**： | 位置 | 作用范围 | 典型用途 | |------|---------|---------| | `~/.claude/CLAUDE.md` | 全局所有项目 | 个人编码风格偏好 | | `项目根/CLAUDE.md` | 单个项目，提交到 Git | 团队共享的项目规范 | | `项目根/.claude/CLAUDE.md` | 单个项目，提交到 Git | 更详细的项目配置 | ### 5.3 编写你的第一个 CLAUDE.md 在项目根目录创建 `CLAUDE.md`： ```markdown # 项目：任务管理 API ## 技术栈 - Python 3.12 + FastAPI - PostgreSQL 15 - SQLAlchemy ORM - pytest 测试框架 ## 代码规范 - 使用 type hints，所有函数必须有类型注解 - 遵循 PEP 8 命名规范 - API 路由统一使用 kebab-case：/user-profile - 错误处理使用 FastAPI HTTPException ## 项目结构 - app/api/ - API 路由定义 - app/models/ - SQLAlchemy 模型 - app/schemas/ - Pydantic 数据模型 - app/services/ - 业务逻辑层 - tests/ - 测试文件 ## 测试要求 - 运行测试命令：pytest tests/ -v - 新增 API 端点必须附带测试 - 测试覆盖率目标：> 80% ## Git 规范 - 不要自动 commit - commit message 使用中文 - 分支命名：feature/xxx, fix/xxx ``` **CLAUDE.md 的最佳实践**： 1. **具体而非模糊**：写 "使用 pnpm，不要用 npm" 而非 "使用包管理器" 2. **包含命令**：写明构建、测试、部署的具体命令 3. **说明项目结构**：帮助 Claude 快速定位文件 4. **设定边界**：明确告诉 Claude 不要做什么（如 "不要修改 .env 文件"） ### 5.4 settings.json 配置文件 `settings.json` 控制工具行为、权限和环境变量等。查看当前配置： ```bash cat ~/.claude/settings.json ``` 一个典型的配置文件： ```json { "env": { "ANTHROPIC_API_KEY": "sk-ant-xxxxx" }, "permissions": { "allow": [ "Bash(git log:*)", "Bash(npm test:*)", "Read", "Glob", "Grep" ], "deny": [ "Bash(rm -rf:*)" ] } } ``` **权限规则格式**： ``` 工具名(命令模式) ``` 示例： - `"Read"` — 允许所有文件读取 - `"Bash(git:*)"` — 允许所有 git 开头的命令 - `"Bash(npm test:*)"` — 允许 npm test 及其参数 - `"Edit"` — 允许所有文件编辑 --- ## 六、交互式会话基础操作 ### 6.1 启动与基本操作 ```bash # 进入项目目录 cd ~/my-project # 启动交互式会话 claude # 继续上一次对话 claude -c # 恢复指定会话（提供会话 ID） claude -r # 使用指定模型 claude --model sonnet claude --model opus ``` ### 6.2 核心斜杠命令 在交互式会话中，使用 `/` 开头的命令执行特定操作： | 命令 | 功能 | 使用场景 | |------|------|---------| | `/help` | 显示帮助信息 | 忘了怎么用的时候 | | `/login` | 切换/重新认证 | 账户过期或切换用户 | | `/resume` | 恢复历史会话 | 继续之前未完成的工作 | | `/compact` | 压缩上下文窗口 | 对话过长导致响应变慢 | | `/clear` | 清空当前对话 | 开始一个新话题 | | `/model` | 切换模型 | 需要更强/更快的模型 | | `/cost` | 查看当前会话花费 | 监控 API 用量 | | `/memory` | 查看/编辑记忆存储 | 管理持久化知识 | | `/permissions` | 管理工具权限 | 调整安全策略 | | `/mcp` | 管理 MCP 服务器 | 配置外部工具连接 | ### 6.3 键盘快捷键 | 快捷键 | 功能 | |--------|------| | `Enter` | 发送消息 | | `Shift + Enter` | 换行（多行输入） | | `Escape` | 取消当前操作/取消 AI 响应 | | `Ctrl + C` | 中断当前操作 | | `Tab` | 自动补全文件名/命令 | ### 6.4 非交互式模式（-p 模式） `-p`（print）模式适合脚本化和管道操作： ```bash # 单次提问并输出结果 claude -p "解释这个项目的目录结构" # 管道输入 echo "什么是 REST API?" | claude -p # 指定输出格式为 JSON claude -p "列出所有 TODO 注释" --output-format json # 设置预算上限 claude -p "重构这个函数" --max-budget-usd 0.5 # 流式 JSON 输出（适合程序集成） claude -p "分析代码质量" --output-format stream-json ``` --- ## 七、实战案例：从零构建一个 Todo API 现在让我们通过一个完整的实战项目，体验 Claude Code 的完整工作流。 ### 7.1 创建项目 ```bash # 创建项目目录 mkdir ~/todo-api && cd ~/todo-api # 初始化 Git 仓库 git init # 初始化 Python 项目 python3 -m venv venv source venv/bin/activate pip install fastapi uvicorn sqlalchemy pytest httpx # 保存依赖 pip freeze > requirements.txt ``` ### 7.2 编写 CLAUDE.md ```bash cat > CLAUDE.md << 'EOF' # Todo API 项目 ## 技术栈 - Python 3.12 + FastAPI - SQLAlchemy (SQLite，开发环境) - pytest + httpx 测试 ## 代码规范 - 所有函数使用 type hints - 遵循 PEP 8 - API 路由前缀：/api/v1 ## 项目结构 - app/main.py - 应用入口 - app/models.py - 数据模型 - app/schemas.py - Pydantic 模型 - app/database.py - 数据库配置 - tests/ - 测试目录 ## 测试 - 命令：pytest tests/ -v - 每个 API 端点必须有对应测试 ## 规则 - 不要自动 commit - 不要修改 .env 文件 - 修改代码后主动运行测试验证 EOF ``` ### 7.3 使用 Claude Code 生成代码 启动 Claude Code： ```bash claude ``` 在交互式会话中输入以下提示词（逐步执行）： **第一步：生成项目骨架** ``` 请帮我创建一个 Todo API 项目的基础结构，包括： 1. app/main.py - FastAPI 应用入口 2. app/models.py - Todo 数据模型（字段：id, title, description, completed, created_at） 3. app/schemas.py - Pydantic 请求/响应模型 4. app/database.py - SQLite 数据库配置 要求：使用 SQLAlchemy 2.0 风格，支持异步操作 ``` **预期结果**：Claude Code 将创建 4 个文件，每个文件都有完整的代码实现。 **第二步：生成 CRUD 路由** ``` 在 app/api/ 目录下创建 todo 路由，包含以下端点： - GET /api/v1/todos - 获取所有 todo（支持分页和过滤） - GET /api/v1/todos/{id} - 获取单个 todo - POST /api/v1/todos - 创建 todo - PUT /api/v1/todos/{id} - 更新 todo - DELETE /api/v1/todos/{id} - 删除 todo 同时更新 main.py 注册路由 ``` **第三步：生成测试** ``` 为所有 todo API 端点编写测试，放在 tests/test_todo.py 中。 使用 httpx 的 AsyncClient，测试数据库用独立的 SQLite 文件。 覆盖：创建、读取、更新、删除、分页、错误处理 ``` **第四步：运行测试验证** ``` 运行所有测试，确保通过 ``` Claude Code 会执行 `pytest tests/ -v` 并报告结果。 ### 7.4 使用 Claude Code 调试 故意引入一个 bug 来体验调试流程。在交互式会话中： ``` 我在创建 todo 时返回了 500 错误，错误信息是 "column 'created_at' does not exist"。 请帮我找出问题并修复。 ``` Claude Code 会： 1. 读取相关文件（models.py、schemas.py、database.py） 2. 定位问题（可能是数据库迁移未执行） 3. 提出修复方案 4. 执行修复并重新运行测试 ### 7.5 Git 操作 ``` 请帮我查看当前的代码变更，准备提交。 ``` Claude Code 会执行 `git status` 和 `git diff`，展示所有变更，等待你确认后再提交。  > *图表 4* --- ## 八、进阶操作速查 ### 8.1 上下文管理 当对话过长时，Claude Code 的响应会变慢。使用以下方法管理上下文： ```bash # 压缩对话历史（保留关键信息） > /compact # 手动指定压缩重点 > /compact 保留数据库模型和API路由相关的讨论 # 清空对话重新开始 > /clear ``` ### 8.2 多文件操作 ``` 请将所有 API 路由中的错误处理统一改为使用 app/exceptions.py 中定义的自定义异常类 ``` Claude Code 能够一次性修改多个文件并保持一致性。 ### 8.3 代码审查 ``` 审查 app/api/todos.py 的代码质量，关注： 1. 安全漏洞（SQL注入、XSS等） 2. 性能问题（N+1查询等） 3. 代码风格一致性 ``` ### 8.4 使用 Task 子代理 对于复杂任务，Claude Code 可以启动子代理并行处理： ``` 请同时完成以下任务： 1. 搜索整个项目中所有使用 print() 调试语句的地方，替换为 logging 2. 检查所有 API 端点是否有认证保护 3. 为缺少 docstring 的公共函数添加文档 ``` --- ## 九、扩展生态概览 安装完成后，你可以逐步探索 Claude Code 的扩展能力： ### 9.1 Skills（技能） Skills 是最常用的扩展，本质上是 Markdown 格式的指令文件。放在 `~/.claude/skills/` 目录下，可通过 `/skill-name` 调用。 安装方式： ```bash # 通过插件安装 claude plugin install # 手动创建 skill mkdir -p ~/.claude/skills/my-skill cat > ~/.claude/skills/my-skill/skill.md << 'EOF' --- name: my-skill description: 我的自定义技能 --- # My Skill 执行自定义工作流的详细步骤... EOF ``` ### 9.2 MCP（Model Context Protocol） MCP 让 Claude Code 连接外部服务（数据库、浏览器、API 等）： ```bash # 添加 MCP 服务器 claude mcp add my-server -- npx -y @some/mcp-server # 查看已配置的 MCP 服务器 claude mcp list # 测试 MCP 连接 claude mcp test my-server ``` ### 9.3 Hooks（钩子） Hooks 在特定事件发生时自动执行脚本，如每次文件编辑后自动运行 linter： 在 `.claude/settings.json` 中配置： ```json { "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "command": "npx eslint --fix $CLAUDE_FILE_PATH" } ] } } ``` ### 9.4 扩展功能对比  > *图表 5* | 扩展 | 触发方式 | 典型场景 | 学习成本 | |------|---------|---------|---------| | CLAUDE.md | 自动（每次会话） | 项目规范、编码风格 | 低 | | Skills | `/command` 手动触发 | 部署流程、代码生成模板 | 中 | | MCP | Claude 自动调用 | 数据库查询、浏览器控制 | 中高 | | Hooks | 事件自动触发 | 保存后自动格式化、测试 | 中 | | Plugins | 安装后自动集成 | 团队共享工具集 | 低（使用现成的） | --- ## 十、常见问题与故障排除 ### 10.1 安装类问题 **Q：安装后 `claude` 命令找不到** ```bash # 检查安装路径 which claude # 如果为空，检查 npm 全局路径 npm config get prefix # 确保 /bin 在 PATH 中 export PATH="$(npm config get prefix)/bin:$PATH" ``` **Q：macOS 提示"无法打开，因为无法验证开发者"** ```bash # 允许运行 xattr -d com.apple.quarantine $(which claude) ``` ### 10.2 认证类问题 **Q：登录后仍然提示未认证** ```bash # 重新登录 claude auth logout claude auth login ``` **Q：API Key 方式认证失败** 确认 Key 格式正确（以 `sk-ant-` 开头），且未过期。检查环境变量： ```bash echo $ANTHROPIC_API_KEY ``` ### 10.3 使用类问题 **Q：Claude Code 响应很慢** - 使用 `/compact` 压缩上下文 - 指定更快的模型：`claude --model haiku` - 拆分大任务为小步骤 **Q：Claude Code 修改了不该修改的文件** 在 CLAUDE.md 中明确设定边界： ```markdown ## 不要修改的文件 - .env / .env.local - docker-compose.yml - migrations/ 目录下的文件 ``` **Q：权限提示太频繁** 在 `settings.json` 的 `permissions.allow` 中添加常用操作： ```json { "permissions": { "allow": [ "Bash(pytest:*)", "Bash(python:*)", "Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)", "Read", "Glob", "Grep" ] } } ``` --- ## 十一、完整工作流总结  > *图表 6* --- ## 延伸阅读 - [Claude Code 官方文档](https://code.claude.com/docs/en/quickstart) — 最权威的参考 - [Claude Code 100+ Tips（GitHub）](https://github.com/januff/claude-code-tips) — 社区维护的技巧集 - [Claude Code 扩展机制详解](https://alexop.dev/posts/understanding-claude-code-full-stack/) — MCP、Skills、Hooks 深度解析 - [Claude Code 权限配置指南](https://code.claude.com/docs/en/permissions) — 安全配置最佳实践 - [Claude Code 最佳实践（官方）](https://code.claude.com/docs/en/best-practices) — 高效使用模式 --- ## 训练营适用性评估 | 维度 | 评估 | |------|------| | **适合训练营类型** | AI编程入门营、工具链训练营、开发者效率提升营 | | **预计教学时长** | 3-4 小时（含实操练习） | | **学员前置要求** | 基本终端操作能力、任意编程语言基础、Git 基础概念 | | **实操环节占比** | 约 60%（安装配置 30 分钟 + 实战项目 90 分钟 + 调试探索 60 分钟） | | **考核建议** | 学员独立完成一个包含 CRUD API + 测试 + Git 提交的微型项目 | > [!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 等场景全覆盖。