# Claude Code 零基础入门：安装配置与第一个项目 ## 概述 本教程面向**零基础开发者**，从零开始讲解 Claude Code 的安装、认证、配置，直到完成第一个 AI 辅助编程项目。学完本教程，你将掌握 Claude Code 的核心工作流、常用命令和项目级配置方法，能够在日常开发中独立使用 Claude Code 提升编码效率。 **适用人群**：有基本终端操作经验的开发者、想尝试 AI 辅助编程的工程师、对 Claude Code 感兴趣的技术爱好者。 --- ## 一、Claude Code 是什么 Claude Code 是 Anthropic 推出的**命令行 AI 编程助手**，它不是一个简单的聊天机器人，而是一个具备完整工具链的智能 Agent： - **读写文件**：直接在你的项目目录中读取、创建、编辑代码文件 - **执行命令**：运行 shell 命令、启动测试、安装依赖 - **搜索代码**：在代码库中按文件名或内容搜索 - **管理 Git**：提交代码、创建分支、发起 Pull Request - **浏览器操作**：通过 MCP（Model Context Protocol）连接浏览器进行测试 与在网页端使用 Claude 不同，Claude Code 嵌入在你的开发工作流中，能理解整个项目的上下文，进行连贯的多步骤任务。  > *图表 1* --- ## 二、前置条件 ### 2.1 系统要求 | 项目 | 最低要求 | 推荐 | |------|----------|------| | 操作系统 | macOS 12+、Ubuntu 20.04+、Windows 10+ (WSL2) | macOS 14+、Ubuntu 22.04+ | | Node.js | v18.0+ | v20+ 或 v22+ | | npm | v8.0+ | v10+ | | 内存 | 4 GB | 8 GB+ | | 网络 | 能访问 Anthropic API 或代理 | 稳定的网络连接 | ### 2.2 认证方式（选择其一） Claude Code 支持两种认证方式： 1. **Anthropic API Key**：通过 API 直接调用，按 token 计费，适合开发者 2. **Claude 订阅账户**（Pro/Max/Team/Enterprise）：通过 OAuth 登录，使用订阅额度，适合个人用户 ### 2.3 检查你的环境 打开终端，逐条运行以下命令确认环境： ```bash # 检查 Node.js 版本（需要 >= 18） node -v # 预期输出类似：v22.22.0 # 检查 npm 版本 npm -v # 预期输出类似：10.9.4 # 检查 git 是否安装 git --version # 预期输出类似：git version 2.43.0 ``` 如果 `node -v` 报错或版本低于 18，需要先安装 Node.js： ```bash # macOS（使用 Homebrew） brew install node # Ubuntu/Debian curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs # Windows（使用 winget） winget install OpenJS.NodeJS.LTS ``` --- ## 三、安装 Claude Code ### 3.1 全局安装 ```bash npm install -g @anthropic-ai/claude-code ``` 安装完成后验证： ```bash claude --version # 预期输出类似：2.1.56 (Claude Code) ``` > **国内用户注意**：如果 npm 安装速度慢，可以先配置镜像源： > ```bash > npm config set registry https://registry.npmmirror.com > ``` ### 3.2 首次启动与认证 进入你的项目目录（或任意空目录），启动 Claude Code： ```bash mkdir -p ~/my-first-claude-project cd ~/my-first-claude-project claude ``` **认证流程**（首次启动会自动触发）： **方式 A：API Key 认证** ```bash # 设置 API Key export ANTHROPIC_API_KEY="sk-ant-xxxxx" # 或者使用 claude auth 命令 claude auth ``` **方式 B：订阅账户认证** 启动 `claude` 后会显示一个 OAuth 链接，在浏览器中打开并登录你的 Claude 账户即可。 **方式 C：第三方 API 端点**（如使用国内代理或其他兼容 API） 在 `~/.claude/settings.json` 中配置： ```json { "env": { "ANTHROPIC_BASE_URL": "https://your-api-endpoint.com/api/anthropic", "ANTHROPIC_AUTH_TOKEN": "your-token-here" } } ``` 认证成功后，你会看到 Claude Code 的交互式提示符： ``` ╭──────────────────────────────────────────────╮ │ │ │ Welcome to Claude Code! │ │ │ ╰──────────────────────────────────────────────╯ > ``` --- ## 四、核心概念速览 在开始实战之前，理解以下几个核心概念会让你后续操作事半功倍。 ### 4.1 交互模式 vs 非交互模式 | 模式 | 启动方式 | 用途 | |------|----------|------| | 交互模式 | `claude` | 日常开发，多轮对话 | | 单次提问 | `claude "你的问题"` | 快速提问，获取答案后退出 | | 管道模式 | `claude -p "问题"` | 脚本集成，输出纯文本 | | 继续上次 | `claude -c` | 恢复最近的对话 |  > *图表 2* ### 4.2 权限系统 Claude Code 的每次工具调用（读写文件、执行命令等）默认需要你的**手动确认**。这确保了安全性： - **Bash 命令**：执行 shell 命令前需确认 - **文件编辑**：修改文件前需确认 - **文件读取**：默认自动允许 你可以通过权限模式调整确认频率： ```bash # 默认模式：关键操作需要确认 claude --permission-mode default # 仅编辑需确认 claude --permission-mode acceptEdits # 计划模式：只做规划不执行 claude --permission-mode plan # 跳过所有确认（仅在可信沙箱环境中使用！） claude --dangerously-skip-permissions ``` ### 4.3 上下文管理 Claude Code 的上下文窗口是有限的。在长对话中，你需要主动管理上下文： - **`/compact`**：压缩对话历史，保留关键信息 - **`/clear`**：清空当前对话，重新开始 - **CLAUDE.md**：项目级指令文件，每次对话自动加载 --- ## 五、第一个项目：用 Claude Code 构建一个 Todo 应用 现在，让我们通过一个完整的实战项目来体验 Claude Code 的工作流。我们将创建一个命令行 Todo 应用。 ### 5.1 项目初始化 ```bash # 创建项目目录 mkdir -p ~/todo-app cd ~/todo-app # 初始化 git 仓库 git init # 启动 Claude Code claude ``` ### 5.2 初始化项目指令（CLAUDE.md） 在 Claude Code 交互界面中，输入： ``` 请帮我创建一个 CLAUDE.md 文件，内容如下： - 这是一个 Node.js 命令行 Todo 应用 - 使用纯 JavaScript，不用框架 - 数据存储在 JSON 文件中 - 代码风格简洁，函数有清晰的注释 ``` Claude Code 会为你创建一个 `CLAUDE.md` 文件。这个文件是 Claude Code 的"项目说明书"，每次启动新对话时自动读取，确保 Claude 理解你的项目规范。 ### 5.3 让 Claude 写代码 在交互界面中，直接用自然语言描述你的需求： ``` 帮我创建一个命令行 Todo 应用，需要以下功能： 1. 添加任务：todo add "买菜" 2. 列出所有任务：todo list 3. 完成任务：todo done 1 4. 删除任务：todo delete 1 ``` Claude Code 会： 1. 分析需求，规划文件结构 2. 创建 `package.json` 3. 创建主程序文件 `index.js` 4. 创建数据存储模块 **预期生成的项目结构**： ``` todo-app/ ├── CLAUDE.md # 项目指令 ├── package.json # 项目配置 ├── index.js # 主程序入口 ├── todos.json # 数据存储（运行后生成） └── README.md # 项目说明（可选） ``` ### 5.4 审查并接受修改 Claude Code 在创建或修改文件时会显示 diff 预览： ``` Claude wants to create todo-app/index.js: ──────────────────────────────────────── + const fs = require('fs'); + const path = require('path'); + + const DATA_FILE = path.join(__dirname, 'todos.json'); + + function loadTodos() { + ... + } ──────────────────────────────────────── Accept? (y/n) ``` 输入 `y` 确认。你也可以输入 `n` 拒绝并让 Claude 修改方案。 ### 5.5 测试应用 在 Claude Code 中直接让它帮你测试： ``` 请运行这个应用，测试所有功能是否正常 ``` Claude 会执行类似以下命令： ```bash # 添加几个任务 node index.js add "学习 Claude Code" node index.js add "写一篇博客" node index.js add "部署到生产环境" # 列出所有任务 node index.js list # 完成第一个任务 node index.js done 1 # 再次列出 node index.js list ``` **预期输出**： ``` ✓ 任务已添加：学习 Claude Code ✓ 任务已添加：写一篇博客 ✓ 任务已添加：部署到生产环境 📋 待办事项： 1. [ ] 学习 Claude Code 2. [ ] 写一篇博客 3. [ ] 部署到生产环境 ✓ 任务 1 已完成 📋 待办事项： 1. [x] 学习 Claude Code 2. [ ] 写一篇博客 3. [ ] 部署到生产环境 ``` ### 5.6 修复问题（模拟真实开发流程） 如果测试中发现了问题（比如边界情况处理不当），直接告诉 Claude： ``` 删除任务后再列出，发现序号没有重新排列，请修复这个问题 ``` Claude 会定位相关代码、生成修复补丁、再次测试，形成完整的修复闭环。 --- ## 六、常用命令速查 ### 6.1 CLI 启动参数 | 命令 | 说明 | |------|------| | `claude` | 启动交互式会话 | | `claude "问题"` | 单次提问模式 | | `claude -p "问题"` | 纯文本输出模式（适合管道） | | `claude -c` | 继续上次对话 | | `claude -r ` | 恢复指定会话 | | `claude --model sonnet` | 指定使用的模型 | | `claude --worktree` | 在独立 git worktree 中工作 | | `claude --allowedTools "Bash Edit Read"` | 限制可用工具 | | `claude --max-budget-usd 1.0` | 限制单次会话花费上限 | ### 6.2 交互式斜杠命令 在交互模式中，输入 `/` 开头的命令可以控制会话： | 命令 | 说明 | |------|------| | `/help` | 查看所有可用命令 | | `/init` | 初始化项目的 CLAUDE.md 和配置 | | `/compact` | 压缩对话历史，释放上下文空间 | | `/clear` | 清空当前对话 | | `/cost` | 查看当前会话的 token 消耗 | | `/model` | 切换模型（Sonnet / Opus / Haiku） | | `/review` | 让 Claude 审查代码变更 | | `/pr` | 创建 Pull Request | | `/commit` | 生成提交信息并提交 | | `/mcp` | 管理 MCP 服务器 | | `/agents` | 查看已配置的 Agent | ### 6.3 快捷键 | 快捷键 | 功能 | |--------|------| | `Escape` | 中断当前操作 / 取消输入 | | `Ctrl+C` | 取消当前操作 | | `Ctrl+D` | 退出 Claude Code | | `↑ / ↓` | 浏览历史输入 | | `Tab` | 自动补全文件路径 | --- ## 七、项目配置详解 ### 7.1 CLAUDE.md — 项目级指令 `CLAUDE.md` 是 Claude Code 最核心的配置文件，它定义了 Claude 在本项目中的行为准则。 **放置位置和优先级**： ``` CLAUDE.md → 全局指令（用户主目录） 项目根/CLAUDE.md → 项目级指令（最高优先级） 项目根/.claude/CLAUDE.md → 项目级指令（等同上面） ``` **一个实用的 CLAUDE.md 示例**： ```markdown # 项目规范 ## 技术栈 - 前端：React 19 + TypeScript + Tailwind CSS - 后端：Node.js + Express + PostgreSQL - 测试：Vitest + Playwright ## 编码规范 - 使用 TypeScript strict 模式 - 函数必须有类型注解 - 变量使用 camelCase，类型使用 PascalCase - 组件文件使用 PascalCase 命名 ## 项目结构 - src/components/ - React 组件 - src/services/ - API 服务层 - src/utils/ - 工具函数 - tests/ - 测试文件 ## Git 规范 - commit message 使用中文 - 不要自动 commit，等用户确认 - 分支名格式：feature/xxx, fix/xxx ``` ### 7.2 settings.json — 全局设置 Claude Code 的设置文件位于 `~/.claude/settings.json`： ```json { "env": { "ANTHROPIC_API_KEY": "sk-ant-xxxxx", "API_TIMEOUT_MS": "300000" }, "theme": "dark", "verbose": false, "enabledPlugins": { "superpowers@claude-plugins-official": true } } ``` **设置文件的层级**（从低到高优先级）：  > *图表 3* ### 7.3 权限配置 在 `settings.json` 或 `settings.local.json` 中可以配置权限白名单，减少重复确认： ```json { "permissions": { "allow": [ "Bash(node:*)", "Bash(npm:*)", "Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)", "Read", "Glob", "Grep" ], "deny": [ "Bash(rm -rf:*)", "Bash(git push --force:*)" ] } } ``` > **安全提示**：永远不要在共享的 `settings.json` 中配置跳过权限确认。个人本地的 `settings.local.json` 可以适当放宽，但仍需谨慎。 --- ## 八、完整工作流实战：从需求到部署 下面用一个真实的开发场景串联所有知识点。  > *图表 4* ### 步骤 1：启动并初始化 ```bash cd ~/my-project claude ``` 在交互界面中输入 `/init`，Claude 会分析项目结构并生成 CLAUDE.md 草案。 ### 步骤 2：描述需求 ``` 我需要添加一个用户注册功能： - 邮箱和密码注册 - 密码使用 bcrypt 加密 - 注册成功后发送欢迎邮件 - 包含输入验证 ``` ### 步骤 3：审查代码 Claude 会逐步创建/修改文件。每一处修改都会显示 diff，你逐一确认。 **审查要点**： - 检查是否有安全漏洞（如未做输入过滤） - 确认代码风格符合项目规范 - 验证错误处理是否完善 ### 步骤 4：测试 ``` 请为新注册功能编写单元测试，并运行所有测试确保没有回归 ``` ### 步骤 5：提交 ``` /commit ``` Claude 会分析所有变更，生成规范的 commit message，你可以编辑后确认提交。 --- ## 九、常见问题与解决方案 ### 9.1 安装问题 **问题：`npm install -g` 权限不足** ```bash # 方案 1：使用 sudo（不推荐） sudo npm install -g @anthropic-ai/claude-code # 方案 2：修改 npm 全局路径（推荐） mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc npm install -g @anthropic-ai/claude-code ``` **问题：Node.js 版本过低** ```bash # 使用 nvm 管理 Node.js 版本 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22 ``` ### 9.2 认证问题 **问题：API Key 认证失败** ```bash # 检查 Key 是否正确设置 claude auth status # 重新设置 claude auth login # 使用 API Key export ANTHROPIC_API_KEY="sk-ant-xxxxx" ``` **问题：国内无法连接 Anthropic API** 配置自定义 API 端点，在 `~/.claude/settings.json` 中添加： ```json { "env": { "ANTHROPIC_BASE_URL": "https://your-proxy-endpoint.com/api/anthropic" } } ``` ### 9.3 使用问题 **问题：上下文窗口不够用** 在长对话中，使用 `/compact` 压缩历史。如果问题复杂，考虑用 `/clear` 重新开始，让 Claude 重新读取项目文件。 **问题：Claude 修改了不该改的文件** 这是权限系统的作用场景——在 diff 审查时仔细检查，拒绝不合理的修改。你也可以在 CLAUDE.md 中明确禁止修改某些文件： ```markdown ## 禁止修改 - 不要修改 config/production.env - 不要修改 database/migrations/ 下的文件 - 不要修改 CI/CD 配置文件 ``` **问题：Claude 执行危险命令** 在 settings.json 中配置 deny 规则： ```json { "permissions": { "deny": [ "Bash(rm -rf:*)", "Bash(dropbox:*)", "Bash(git push --force:*)", "Bash(git reset --hard:*)" ] } } ``` --- ## 十、VS Code 集成（可选） 如果你不习惯纯命令行，Claude Code 也支持 VS Code 集成： 1. 在 VS Code 扩展市场搜索 **"Claude Code"** 并安装 2. 打开终端（`Ctrl+`` `），运行 `claude` 启动 3. Claude Code 会自动检测 VS Code 环境，提供更流畅的体验 VS Code 集成的优势： - 编辑器内直接显示 diff - 文件修改实时同步 - 可以通过侧边栏查看 Claude 的操作历史 --- ## 十一、进阶提示 ### 11.1 高效对话技巧 | 技巧 | 示例 | |------|------| | **明确目标** | "在 src/auth.js 中添加 JWT token 验证中间件" | | **指定范围** | "只修改 api/ 目录下的文件" | | **提供上下文** | "这个函数被 x, y, z 三处调用，修改时保持兼容" | | **分步请求** | "先分析问题，再给出方案，最后实施" | | **要求审查** | "修改完成后，请 review 所有变更" | ### 11.2 模型选择  > *图表 5* 使用 `/model` 命令在会话中切换模型，或启动时指定： ```bash claude --model opus # 最强模型，复杂任务 claude --model sonnet # 默认模型，日常开发 claude --model haiku # 快速模型，简单任务 ``` ### 11.3 管道与自动化 Claude Code 的 `-p` 模式非常适合脚本集成： ```bash # 代码审查 git diff main | claude -p "Review this diff for potential bugs" # 自动生成 commit message git diff --staged | claude -p "Generate a concise commit message" # 分析日志 cat error.log | claude -p "分析这些错误日志，找出根本原因" # 批量重构 find src -name "*.js" | claude -p "列出这些文件中使用了旧API的地方" ``` --- ## 十二、学习路径与延伸阅读 掌握基础后，建议按以下路径深入学习：  > *图表 6* **官方资源**： - Anthropic 官方文档：https://docs.anthropic.com/en/docs/claude-code - Claude Code GitHub：https://github.com/anthropics/claude-code - Claude Code 命令参考：https://code.claude.com/docs/en/commands **社区资源**： - Claude Code 完整 Cheat Sheet：https://computingforgeeks.com/claude-code-cheat-sheet/ - 45 条 Claude Code 使用技巧：https://github.com/ykdojo/claude-code-tips - Claude Code 中文教程：https://github.com/hiliyongke/claude-code-tutorial --- ## 训练营适用性评估 | 维度 | 评估 | |------|------| | **适合训练营类型** | AI 编程入门营、前端/后端开发训练营、全栈工程师集训 | | **教学时长** | 2-3 小时（含动手实践） | | **学员基础要求** | 基本的终端操作能力，了解一种编程语言 | | **硬件要求** | 笔记本电脑，已安装 Node.js | | **网络要求** | 能访问 Anthropic API 或代理 | | **建议班级规模** | 15-20 人（保证辅导质量） | | **教学重点** | 实战操作 > 理论讲解，建议 70% 时间用于动手练习 | | **课后作业** | 用 Claude Code 独立完成一个小项目（如个人博客、记账应用） | > [!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 等场景全覆盖。