# Claude Code 入门篇：安装、配置与第一个项目 ## 一、概述 Claude Code 是由 Anthropic 公司推出的命令行 AI 编程助手，它直接运行在你的终端环境中，能够理解整个项目的上下文，帮助你编写代码、调试问题、执行 Git 操作，甚至管理复杂的多文件重构任务。与传统的 IDE 插件不同，Claude Code 是一个独立的 CLI 工具，不依赖于任何特定的编辑器，可以在任何终端环境中使用。 2026 年，Claude Code 经历了重大更新：安装方式从 `npm install` 迁移到了独立的安装脚本和包管理器分发；新增了 Skills（技能）系统、MCP（模型上下文协议）服务器支持、Agent 模式等高级功能。本篇教程作为五轮系列的第一轮，将带你从零开始完成 Claude Code 的安装、配置，并创建你的第一个项目。 **你将学到：** - 如何在不同操作系统上安装 Claude Code - 认证与基础配置方法 - 理解 CLAUDE.md 项目记忆文件的作用 - 使用核心命令完成第一个实战项目 - 常见问题排查与解决 **适合人群：** 零基础开发者，无需事先了解 Claude Code 或 AI 编程工具。 --- ## 二、前置条件 在开始安装之前，请确保你的系统满足以下要求： ### 2.1 系统要求 | 项目 | 要求 | |------|------| | 操作系统 | macOS 12+、Ubuntu 20.04+、Debian 10+、Windows 10+（WSL2） | | Node.js | 18.0 或更高版本 | | 网络环境 | 需要访问 `claude.ai` 和 `anthropic.com` | | 终端 | 任何现代终端（iTerm2、Windows Terminal、GNOME Terminal 等） | ### 2.2 Node.js 安装检查 Claude Code 依赖 Node.js 运行时。打开终端，执行以下命令检查是否已安装： ```bash node --version ``` **预期输出：** ``` v20.11.0 ``` 如果显示 `v18.x.x` 或更高版本，说明满足要求。如果提示"命令未找到"或版本低于 18，需要先安装 Node.js。 **安装 Node.js（推荐使用 nvm）：** ```bash # 安装 nvm（Node Version Manager） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装 Node.js LTS 版本 nvm install --lts # 验证安装 node --version ``` ### 2.3 获取访问权限 Claude Code 提供两种认证方式： 1. **Anthropic API Key**：在 [console.anthropic.com](https://console.anthropic.com) 注册并创建 API Key，按用量付费 2. **Claude Pro/Max 订阅**：拥有 Claude Pro 或 Max 订阅的用户可以直接使用 Claude Code，无需额外 API Key > **建议：** 如果你是初次体验，推荐先使用 Claude Pro 订阅方式，避免 API 费用管理的复杂性。 --- ## 三、安装 Claude Code ### 3.1 安装方式概览  > *图表 1* > **重要提示：** `npm install -g @anthropic-ai/claude-code` 已被官方标记为 **已弃用（DEPRECATED）**。虽然目前仍然可以使用，但官方不再推荐，未来可能移除支持。请使用以下新的安装方式。 ### 3.2 macOS 和 Linux 安装（推荐） **方式一：官方安装脚本（最推荐）** ```bash curl -fsSL https://claude.ai/install.sh | bash ``` **预期输出：** ``` Installing Claude Code... Downloading latest release... Installation complete! Claude Code has been installed to ~/.claude/bin/claude Added ~/.claude/bin to your PATH Please restart your terminal or run: source ~/.bashrc ``` 安装完成后，重新加载 shell 配置： ```bash source ~/.bashrc # 如果使用 bash # 或 source ~/.zshrc # 如果使用 zsh ``` **方式二：Homebrew 安装（仅 macOS）** ```bash brew install --cask claude-code ``` **预期输出：** ``` ==> Downloading claude-code ==> Installing Cask claude-code ==> Moving App to target directory 🍺 /opt/homebrew/Caskroom/claude-code ``` ### 3.3 Windows 安装 **方式一：PowerShell 安装脚本** ```powershell irm https://claude.ai/install.ps1 | iex ``` **方式二：WinGet 包管理器** ```powershell winget install Anthropic.ClaudeCode ``` **方式三：WSL2 环境中安装** 如果你在 Windows 上使用 WSL2（推荐），可以在 WSL2 的 Linux shell 中直接使用 macOS/Linux 的安装方式： ```bash # 在 WSL2 的 Ubuntu/Debian 环境中执行 curl -fsSL https://claude.ai/install.sh | bash ``` ### 3.4 验证安装 ```bash claude --version ``` **预期输出（示例）：** ``` Claude Code v1.0.20 ``` 如果看到版本号输出，说明安装成功。如果提示"命令未找到"，请检查 PATH 配置： ```bash # 检查 claude 可执行文件位置 which claude # 如果使用官方脚本安装，claude 通常在 ~/.claude/bin/ 目录下 echo $PATH | grep -o '[^:]*claude[^:]*' ``` --- ## 四、首次配置与认证 ### 4.1 启动 Claude Code 在终端中输入： ```bash claude ``` 首次启动时，Claude Code 会引导你完成认证流程。 ### 4.2 认证流程  > *图表 2* **方式一：API Key 认证** ```bash claude # 选择 "API Key" 方式 # 粘贴你的 API Key: sk-ant-api03-xxxxx # 按回车确认 ``` **方式二：OAuth 浏览器认证（Claude Pro/Max 用户）** ```bash claude # 选择 "Login with Claude Account" # 终端会显示一个 URL 或自动打开浏览器 # 在浏览器中完成登录授权 # 回到终端，认证自动完成 ``` ### 4.3 基础配置 认证完成后，你可以通过以下方式进行个性化配置： **配置 API 相关设置：** ```bash # 查看当前配置 claude config list # 设置默认模型 claude config set model claude-sonnet-4-20250514 # 设置主题（dark/light） claude config set theme dark ``` **环境变量配置（可选）：** ```bash # 在 ~/.bashrc 或 ~/.zshrc 中添加 export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here" export CLAUDE_CODE_MAX_TURNS=50 # 限制最大对话轮次 ``` > **安全提示：** 永远不要将 API Key 提交到 Git 仓库中。确保 `.env` 和包含密钥的文件已添加到 `.gitignore`。 --- ## 五、理解核心概念 ### 5.1 CLAUDE.md — 项目记忆文件 `CLAUDE.md` 是 Claude Code 最重要的配置文件之一。它放在项目根目录下，为 Claude 提供项目的上下文信息和行为指导。每次 Claude Code 启动时，都会自动读取该文件。 **CLAUDE.md 的作用：** - 告诉 Claude 你的项目是什么、使用什么技术栈 - 定义代码风格偏好和编码规范 - 指定项目结构和关键文件位置 - 设置自动化行为（如测试命令、构建流程） **示例 CLAUDE.md：** ```markdown # 项目：个人博客系统 ## 技术栈 - 前端：React 18 + TypeScript - 后端：Node.js + Express - 数据库：PostgreSQL - 测试：Jest ## 代码规范 - 使用 ESLint + Prettier - 组件使用函数式组件 + Hooks - API 路由统一放在 src/routes/ 目录 ## 常用命令 - 启动开发服务器：npm run dev - 运行测试：npm test - 构建：npm run build ``` ### 5.2 常用命令速查 | 命令 | 说明 | |------|------| | `claude` | 启动交互式会话 | | `claude "你的问题"` | 直接提问（非交互模式） | | `claude --resume` | 恢复上一次会话 | | `/init` | 初始化 CLAUDE.md 文件 | | `/help` | 查看帮助信息 | | `/compact` | 压缩对话上下文（释放 token） | | `/cost` | 查看当前会话的 token 消耗 | | `/clear` | 清除当前会话 | | `/config` | 修改配置 | ### 5.3 工作流程  > *图表 3* --- ## 六、第一个项目：创建命令行待办事项应用 现在让我们通过一个完整的实战项目来体验 Claude Code 的工作流程。我们将创建一个基于 Node.js 的命令行待办事项（TODO）应用。 ### 6.1 创建项目 ```bash # 创建项目目录 mkdir my-todo-app cd my-todo-app # 初始化 Git 仓库（推荐） git init # 初始化 Node.js 项目 npm init -y ``` ### 6.2 使用 /init 创建 CLAUDE.md 启动 Claude Code 并使用 `/init` 命令自动生成项目配置： ```bash claude ``` 进入交互界面后输入： ``` /init ``` Claude Code 会扫描当前目录结构并生成一个初始的 `CLAUDE.md` 文件。你可以在此基础上进行修改。 ### 6.3 描述需求并生成代码 在 Claude Code 的交互界面中，输入以下需求描述： ``` 请帮我创建一个命令行 TODO 应用，要求如下： 1. 使用 Node.js，不需要额外的依赖库 2. 数据存储在本地 JSON 文件中（todos.json） 3. 支持以下命令： - add "任务内容" — 添加新任务 - list — 列出所有任务 - done — 标记任务为完成 - delete — 删除任务 4. 任务包含 id、内容、创建时间、是否完成等字段 5. 列表显示时，用颜色区分已完成和未完成的任务 ``` Claude Code 会分析需求、生成代码，并展示文件变更预览。确认后，它会自动创建以下文件结构： ``` my-todo-app/ ├── CLAUDE.md ├── package.json ├── index.js # 主入口文件 ├── todo.js # TODO 核心逻辑 └── todos.json # 数据存储文件（运行后生成） ``` ### 6.4 测试运行 ```bash # 退出 Claude Code（输入 /exit 或按 Ctrl+C） # 然后在终端中运行应用 # 添加任务 node index.js add "学习 Claude Code 基础" node index.js add "完成第一个项目" node index.js add "尝试 Skills 功能" ``` **预期输出：** ``` ✓ 任务已添加: [1] 学习 Claude Code 基础 ✓ 任务已添加: [2] 完成第一个项目 ✓ 任务已添加: [3] 尝试 Skills 功能 ``` ```bash # 列出所有任务 node index.js list ``` **预期输出：** ``` TODO 列表: ───────────────────────────────────── [1] ○ 学习 Claude Code 基础 (创建于: 2026-05-17 14:30) [2] ○ 完成第一个项目 (创建于: 2026-05-17 14:31) [3] ○ 尝试 Skills 功能 (创建于: 2026-05-17 14:31) ───────────────────────────────────── 总计: 3 个任务, 0 个已完成 ``` ```bash # 标记任务完成 node index.js done 1 # 再次查看列表 node index.js list ``` **预期输出：** ``` ✓ 任务 [1] 已标记为完成 ``` ``` TODO 列表: ───────────────────────────────────── [1] ✓ 学习 Claude Code 基础 (创建于: 2026-05-17 14:30) ✓ 完成 [2] ○ 完成第一个项目 (创建于: 2026-05-17 14:31) [3] ○ 尝试 Skills 功能 (创建于: 2026-05-17 14:31) ───────────────────────────────────── 总计: 3 个任务, 1 个已完成 ``` ### 6.5 持续迭代 你可以在 Claude Code 中继续迭代这个项目。例如： ``` 请给 TODO 应用添加以下功能： 1. 支持设置任务优先级（高/中/低） 2. list 命令支持按优先级排序 3. 添加 search "关键词" 命令来搜索任务 ``` Claude Code 会读取现有代码，理解项目结构，并在不破坏现有功能的前提下添加新特性。 ### 6.6 代码审查与优化 你还可以让 Claude Code 审查和优化代码： ``` 请审查当前项目的代码质量，指出潜在问题并给出优化建议 ``` Claude Code 会： 1. 读取所有相关源文件 2. 分析代码结构、错误处理、边界情况 3. 提出具体的改进建议 4. 在你确认后直接应用修改 --- ## 七、常见问题排查 ### 7.1 安装相关问题 **问题：安装后提示"command not found: claude"** ```bash # 检查安装路径 ls -la ~/.claude/bin/claude # 手动添加到 PATH echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.bashrc source ~/.bashrc # 再次验证 claude --version ``` **问题：curl 安装脚本下载失败** 可能原因及解决方案： ```bash # 1. 检查网络连接 ping -c 3 claude.ai # 2. 如果有代理，设置代理 export https_proxy="http://your-proxy:port" # 3. 使用 Homebrew 作为替代（macOS） brew install --cask claude-code # 4. 手动下载安装（Linux） # 访问 GitHub Releases 页面下载对应平台的二进制文件 ``` **问题：Node.js 版本过低** ```bash # 使用 nvm 安装最新 LTS 版本 nvm install --lts nvm use --lts # 确认版本 node --version # 应该 >= v18.0.0 ``` ### 7.2 认证相关问题 **问题：API Key 认证失败** ```bash # 验证 API Key 是否有效 curl -s https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}' # 如果返回 JSON 响应，说明 Key 有效 # 如果返回 401，说明 Key 无效或已过期 ``` **问题：OAuth 登录超时** - 确保浏览器可以正常访问 `claude.ai` - 检查系统时间是否正确（OAuth 对时间敏感） - 尝试切换到 API Key 方式认证 ### 7.3 使用相关问题 **问题：响应速度慢或经常超时** ```bash # 检查网络延迟 ping -c 3 api.anthropic.com # 尝试使用 /compact 命令压缩上下文 # 在 Claude Code 中输入: /compact # 或限制上下文文件数量 # 在 CLAUDE.md 中添加: # 只在必要时读取 src/ 目录下的文件 ``` **问题：生成代码与项目风格不一致** 确保 `CLAUDE.md` 中包含详细的编码规范说明。你可以使用 `/init` 重新生成，或手动编辑该文件添加更多上下文。 --- ## 八、进阶使用技巧 ### 8.1 管道操作 Claude Code 支持从标准输入接收内容： ```bash # 将错误信息直接传递给 Claude 分析 npm test 2>&1 | claude "分析这些测试错误并给出修复建议" # 分析日志文件 cat error.log | claude "总结这些错误日志的共性问题" ``` ### 8.2 非交互模式 适合脚本化使用： ```bash # 单次提问模式 claude -p "解释这段代码的作用: $(cat index.js)" # 指定输出格式 claude -p "列出这个项目的所有 API 端点" --output-format json ``` ### 8.3 会话管理 ```bash # 恢复上次会话 claude --resume # 查看历史会话 claude --sessions # 继续特定会话 claude --resume ``` ### 8.4 多文件上下文 Claude Code 会自动理解项目上下文，但你也可以显式指定关注的文件： ``` 请重点参考 src/models/user.js 和 src/routes/auth.js， 帮我修复用户注册时的密码验证问题 ``` --- ## 九、延伸阅读 以下是进一步学习 Claude Code 的推荐资源： 1. **官方文档** — [code.claude.com/docs/en/overview](https://code.claude.com/docs/en/overview) — 最权威的参考手册，包含完整的命令文档和配置说明 2. **官方快速入门** — [code.claude.com/docs/en/quickstart](https://code.claude.com/docs/en/quickstart) — 5 分钟快速上手指南 3. **Claude Code Tips 集合** — [github.com/ykdojo/claude-code-tips](https://github.com/ykdojo/claude-code-tips) — 社区维护的 45+ 实用技巧 4. **50 个 Claude Code 技巧** — [getbeam.dev/blog/claude-code-tips](https://getbeam.dev/blog/claude-code-tips) — 深度使用技巧和最佳实践 5. **知乎：Claude Code 全面指南** — 中文社区的深度评测和使用心得分享 6. **掘金：Claude Code 实战系列** — 包含多个真实项目案例的中文教程 7. **GitHub 官方仓库** — [github.com/anthropics/claude-code](https://github.com/anthropics/claude-code) — 源码、Issue 追踪和社区讨论 --- ## 十、训练营考核 完成本篇学习后，请尝试以下实践任务来检验你的掌握程度： ### 基础任务（必做） **任务 1：环境验证** 在终端中执行以下操作并记录结果： 1. 检查 Node.js 版本并确认 >= 18 2. 检查 Claude Code 版本 3. 成功启动 Claude Code 并执行 `/help` 命令 **任务 2：项目初始化** 1. 创建一个新的项目目录 `claude-practice` 2. 使用 `claude` 启动交互会话 3. 使用 `/init` 创建 CLAUDE.md 文件 4. 手动编辑 CLAUDE.md，添加你喜欢的编码规范 **任务 3：第一次对话** 1. 在 Claude Code 中输入："帮我创建一个简单的计算器模块，支持加减乘除" 2. 审查生成的代码 3. 追问："请添加错误处理，处理除以零的情况" 4. 使用 `/cost` 查看本次会话消耗 ### 进阶任务（选做） **任务 4：管道实践** ```bash # 创建一个有 bug 的 JavaScript 文件 echo 'function add(a, b) { return a - b; }' > buggy.js echo 'function divide(a, b) { return a / b; }' >> buggy.js # 让 Claude Code 分析并修复 cat buggy.js | claude "找出代码中的 bug 并修复" ``` **任务 5：迭代开发** 使用 Claude Code 完成以下迭代式开发： 1. 创建一个"猜数字"命令行游戏 2. 添加难度选择功能 3. 添加计分和排行榜 4. 添加游戏记录持久化存储 ### 自我评估标准 | 等级 | 标准 | |------|------| | 通过 | 完成 3 个基础任务，Claude Code 正常工作，能生成可用代码 | | 良好 | 完成所有基础任务 + 1 个进阶任务，理解 CLAUDE.md 的作用 | | 优秀 | 完成所有任务，能灵活使用管道和非交互模式，对工作流程有深入理解 | --- ## 结语 本篇教程覆盖了 Claude Code 的安装、配置和基本使用流程。你已经学会了如何在不同的操作系统上安装 Claude Code、完成认证、创建项目记忆文件，并通过一个完整的 TODO 应用体验了 AI 辅助开发的工作流。 在后续的四轮教程中，我们将深入探索更高级的主题： - **Round 2：Skills 开发实战** — 学习如何创建和使用 Skills 来定制 Claude Code 的行为 - **Round 3：MCP 服务器开发** — 通过模型上下文协议扩展 Claude Code 的工具能力 - **Round 4：Agent 模式与自动化** — 探索 Claude Code 的自主代理模式和自动化工作流 - **Round 5：高级技巧** — 掌握性能优化、多项目管理、团队协作等进阶技巧 现在，打开你的终端，开始你的 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 等场景全覆盖。