# Claude Code新手实操：从安装避坑到首个项目交付
> **学习目标**：读完本文，你将独立完成 Claude Code 的全平台安装、认证配置、权限理解，并能用一个完整的 CLI 工具项目验证整个工作流。适合零编程经验或仅写过后端脚本的开发者。
>
> **适用人群**：首次接触 Claude Code 的开发者、从 ChatGPT/Copilot 迁移过来的工程师、对 AI 辅助编程感兴趣的技术管理者。
---
## 一、前置条件：你需要什么
在安装 Claude Code 之前，确认以下环境就绪：
| 条件 | 最低要求 | 推荐配置 |
|------|---------|---------|
| **操作系统** | macOS 12+、Ubuntu 20.04+、Windows 10+（WSL2） | macOS 14+、Ubuntu 22.04+ |
| **Node.js** | v18.0+ | v20 LTS（通过 `nvm` 安装） |
| **终端** | 系统自带终端 | iTerm2 / Windows Terminal / Warp |
| **Git** | 2.30+ | 最新稳定版 |
| **账号** | Anthropic 账号（API Key 或 Claude Pro/Max 订阅） | Claude Max 订阅（含 API 额度） |
### 1.1 安装 Node.js（推荐 nvm 方式）
```bash
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# 重新加载 shell
source ~/.bashrc # 或 ~/.zshrc
# 安装 Node.js 20 LTS
nvm install 20
nvm use 20
# 验证
node --version # 应输出 v20.x.x
npm --version # 应输出 10.x.x
```
### 1.2 确认 Git 可用
```bash
git --version # 应输出 git version 2.3x+
```
> **Windows 用户注意**：Claude Code 在 Windows 上必须通过 WSL2 运行。安装 WSL2：
> ```powershell
> wsl --install
> ```
> 然后在 WSL2 的 Ubuntu 环境中执行后续所有步骤。
---
## 二、安装 Claude Code：三种方式对比
### 2.1 方式一：npm 全局安装（推荐）
```bash
npm install -g @anthropic-ai/claude-code
```
验证安装：
```bash
claude --version
# 输出示例：1.0.x
```
### 2.2 方式二：VS Code 扩展
在 VS Code 扩展市场搜索 "Claude Code" 并安装。安装后侧边栏会出现 Claude 图标，点击即可在 IDE 内使用。
> **优劣对比**：VS Code 扩展集成了编辑器体验，但 CLI 模式更灵活，支持管道和脚本编排。建议新手两个都装，日常用 VS Code 扩展，复杂任务切 CLI。
### 2.3 方式三：桌面应用（macOS）
从 Anthropic 官网下载 Claude Desktop 应用，内置 Claude Code 功能。适合不习惯终端的用户。
---
## 三、认证配置：三种接入方式
### 3.1 方式一：Claude Pro/Max 订阅（最简单）
如果你已有 Claude Pro 或 Max 订阅，直接运行：
```bash
claude
```
首次启动会弹出浏览器进行 OAuth 登录。登录成功后即可使用，无需 API Key。
### 3.2 方式二：API Key 直连
```bash
# 设置 API Key
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxx"
# 建议写入 shell 配置文件
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc
```
> **安全提示**：永远不要把 API Key 提交到 Git 仓库。在 `.gitignore` 中加入 `.env` 文件。
### 3.3 方式三：国内代理/第三方 API
对于无法直接访问 Anthropic API 的用户，可以配置代理端点：
```bash
export ANTHROPIC_BASE_URL="https://your-proxy-endpoint.com/v1"
export ANTHROPIC_API_KEY="your-key"
```
---
## 四、权限系统：新手最容易忽视的安全门
Claude Code 的权限系统是其安全核心。理解它，是避免"AI 删了我的代码"这类事故的第一步。
### 4.1 权限层级
```mermaid
graph TD
A[启动 Claude Code] --> B{选择权限模式}
B -->|默认| C[交互确认模式]
B -->|--dangerously-skip-permissions| D[自动执行模式]
B -->|--allowedTools| E[白名单模式]
C --> F{操作类型}
F -->|读取文件| G[自动允许]
F -->|写入文件| H[弹窗确认]
F -->|执行命令| I[弹窗确认]
D --> J[所有操作自动执行
⚠️ 仅限受信环境]
E --> K[仅白名单操作自动执行]
```
### 4.2 权限模式选择建议
| 场景 | 推荐模式 | 原因 |
|------|---------|------|
| 学习阶段 | 交互确认（默认） | 逐步理解 Claude 做什么 |
| 日常开发 | 交互确认 | 对关键操作保持人工审核 |
| CI/CD 管道 | `--dangerously-skip-permissions` | 自动化需要无人值守 |
| 敏感项目 | 白名单模式 | 精确控制允许的操作 |
### 4.3 权限配置文件
Claude Code 的权限可以通过 `.claude/settings.json` 持久化：
```json
{
"permissions": {
"allow": [
"Bash(npm test)",
"Bash(git status)",
"Bash(git diff *)",
"Read(*)"
],
"deny": [
"Bash(rm -rf *)",
"Bash(curl * | bash)"
]
}
}
```
> **新手第一原则**：学习阶段，不要配置 `deny` 列表之外的任何自动执行。每次 Claude 请求执行命令时，仔细阅读弹出的确认信息。
---
## 五、CLAUDE.md：给 Claude 的项目简历
CLAUDE.md 是 Claude Code 理解你项目的核心配置文件。没有它，Claude 就像一个不了解项目背景的新员工。
### 5.1 CLAUDE.md 的三层架构
```mermaid
graph LR
A["~/.claude/CLAUDE.md
全局配置"] --> B["项目根目录/CLAUDE.md
项目配置"]
B --> C["子目录/CLAUDE.md
模块配置"]
style A fill:#e1f5fe
style B fill:#fff3e0
style C fill:#e8f5e9
```
- **全局配置** `~/.claude/CLAUDE.md`：所有项目共享的偏好（语言、风格）
- **项目配置** `项目根目录/CLAUDE.md`：项目特定的规则和结构
- **模块配置** `子目录/CLAUDE.md`：子模块的特殊规则
### 5.2 最小可用模板
创建你的第一个 CLAUDE.md：
```bash
mkdir -p my-first-project && cd my-first-project
git init
```
```markdown
# CLAUDE.md
## 项目概述
一个用 Node.js 编写的命令行 TODO 管理工具。
## 技术栈
- 运行时：Node.js 20 LTS
- 语言：JavaScript（ES Module）
- 测试：Vitest
- 无外部依赖
## 常用命令
- 运行：`node src/index.js`
- 测试：`npx vitest`
- 代码风格检查：无（项目简单）
## 项目结构
- `src/index.js` — 入口文件
- `src/todo.js` — TODO 核心逻辑
- `src/storage.js` — 数据持久化
- `tests/` — 测试文件
## 编码规范
- 使用 ES Module（import/export）
- 函数使用驼峰命名
- 优先使用 const，避免 var
- 每个函数不超过 20 行
## 注意事项
- 不要安装额外的 npm 包
- 数据存储在项目根目录的 `.todos.json` 文件中
- 所有用户交互通过 console.log/console readline
```
### 5.3 生成 CLAUDE.md 的快捷方式
Claude Code 内置了 `/init` 命令，可以自动分析项目并生成 CLAUDE.md：
```bash
claude
> /init
```
Claude 会扫描项目结构、package.json、README 等文件，自动生成一份基础 CLAUDE.md，你可以在此基础上修改。
---
## 六、核心交互：会话与命令速查
进入 Claude Code 后，你会看到一个交互式提示符。以下是必须掌握的核心操作：
### 6.1 斜杠命令速查表
| 命令 | 功能 | 使用频率 |
|------|------|---------|
| `/init` | 初始化 CLAUDE.md | 每个项目一次 |
| `/help` | 查看帮助 | 按需 |
| `/compact` | 压缩对话历史，释放上下文 | 频繁 |
| `/clear` | 清除当前对话 | 按需 |
| `/cost` | 查看当前会话 Token 消耗 | 频繁 |
| `/review` | 让 Claude 审查代码变更 | 按需 |
| `/mcp` | 管理 MCP 服务器 | 按需 |
| `/fast` | 切换快速模式（同模型，更快输出） | 按需 |
| `/model` | 切换模型（opus/sonnet/haiku） | 按需 |
### 6.2 快捷键
| 快捷键 | 功能 |
|--------|------|
| `Enter` | 发送消息 |
| `Shift+Enter` | 换行（不发送） |
| `Ctrl+C` | 取消当前操作 |
| `Ctrl+D` | 退出 Claude Code |
| `↑/↓` | 浏览历史消息 |
| `Tab` | 自动补全文件路径 |
### 6.3 CLI 标志位（启动参数）
```bash
# 非交互模式：执行单个提示词
claude -p "解释这个项目的结构"
# 管道模式：结合 Unix 管道使用
cat error.log | claude -p "分析这段错误日志"
# 指定模型
claude --model sonnet
# 继续上次会话
claude --continue
# 恢复最近一次会话
claude --resume
```
---
## 七、实战项目：从零构建一个 CLI TODO 工具
这是本文的核心部分。我们将用 Claude Code 从零开始，一步步构建一个可用的命令行 TODO 管理工具。
### 7.1 项目初始化
```bash
# 创建项目目录
mkdir -p todo-cli && cd todo-cli
git init
# 创建 package.json
cat > package.json << 'EOF'
{
"name": "todo-cli",
"version": "1.0.0",
"type": "module",
"main": "src/index.js",
"scripts": {
"start": "node src/index.js",
"test": "npx vitest run"
}
}
EOF
```
### 7.2 与 Claude Code 协作的第一条指令
启动 Claude Code：
```bash
claude
```
输入你的第一条项目指令：
```
请帮我创建一个命令行 TODO 管理工具。要求：
1. 支持添加、列出、完成、删除 TODO 项
2. 数据持久化到 .todos.json 文件
3. 使用 ES Module 语法
4. 不使用任何第三方依赖
5. 每个操作有清晰的命令行输出
```
Claude Code 会：
1. 分析需求，规划文件结构
2. 逐一创建文件，每步请求你的确认
3. 运行测试验证功能
### 7.3 预期生成的文件结构
```
todo-cli/
├── CLAUDE.md
├── package.json
├── src/
│ ├── index.js # 入口：解析命令行参数
│ ├── todo.js # 核心：TODO 增删改查
│ └── storage.js # 持久化：读写 JSON 文件
├── tests/
│ ├── todo.test.js
│ └── storage.test.js
└── .todos.json # 运行时生成
```
### 7.4 核心代码示例（Claude 会帮你生成类似代码）
`src/storage.js`：
```javascript
import { readFile, writeFile } from 'fs/promises';
import { existsSync } from 'fs';
const FILE_PATH = '.todos.json';
export async function loadTodos() {
if (!existsSync(FILE_PATH)) {
return [];
}
const data = await readFile(FILE_PATH, 'utf-8');
return JSON.parse(data);
}
export async function saveTodos(todos) {
await writeFile(FILE_PATH, JSON.stringify(todos, null, 2), 'utf-8');
}
```
`src/todo.js`：
```javascript
import { loadTodos, saveTodos } from './storage.js';
export async function addTodo(text) {
const todos = await loadTodos();
const newTodo = {
id: Date.now(),
text,
done: false,
createdAt: new Date().toISOString()
};
todos.push(newTodo);
await saveTodos(todos);
console.log(`✅ 已添加: ${text} (ID: ${newTodo.id})`);
}
export async function listTodos() {
const todos = await loadTodos();
if (todos.length === 0) {
console.log('📋 暂无 TODO 项');
return;
}
console.log('📋 TODO 列表:');
todos.forEach(t => {
const status = t.done ? '✅' : '⬜';
console.log(` ${status} [${t.id}] ${t.text}`);
});
}
export async function completeTodo(id) {
const todos = await loadTodos();
const todo = todos.find(t => t.id === Number(id));
if (!todo) {
console.log(`❌ 未找到 ID: ${id}`);
return;
}
todo.done = true;
await saveTodos(todos);
console.log(`🎉 已完成: ${todo.text}`);
}
export async function deleteTodo(id) {
const todos = await loadTodos();
const index = todos.findIndex(t => t.id === Number(id));
if (index === -1) {
console.log(`❌ 未找到 ID: ${id}`);
return;
}
const removed = todos.splice(index, 1)[0];
await saveTodos(todos);
console.log(`🗑️ 已删除: ${removed.text}`);
}
```
`src/index.js`：
```javascript
import { addTodo, listTodos, completeTodo, deleteTodo } from './todo.js';
const [,, command, ...args] = process.argv;
async function main() {
switch (command) {
case 'add':
if (!args.length) {
console.log('用法: node src/index.js add <待办事项>');
break;
}
await addTodo(args.join(' '));
break;
case 'list':
await listTodos();
break;
case 'done':
await completeTodo(args[0]);
break;
case 'delete':
await deleteTodo(args[0]);
break;
default:
console.log('用法: node src/index.js [参数]');
}
}
main().catch(console.error);
```
### 7.5 运行与验证
```bash
# 添加 TODO
node src/index.js add "学习 Claude Code 安装"
# 输出：✅ 已添加: 学习 Claude Code 安装 (ID: 1748600000000)
node src/index.js add "完成第一个项目"
node src/index.js add "写 CLAUDE.md"
# 列出所有
node src/index.js list
# 📋 TODO 列表:
# ⬜ [1748600000000] 学习 Claude Code 安装
# ⬜ [1748600000001] 完成第一个项目
# ⬜ [1748600000002] 写 CLAUDE.md
# 完成 TODO
node src/index.js done 1748600000000
# 🎉 已完成: 学习 Claude Code 安装
# 删除 TODO
node src/index.js delete 1748600000002
# 🗑️ 已删除: 写 CLAUDE.md
```
### 7.6 让 Claude Code 写测试
在 Claude Code 会话中输入：
```
请为 todo.js 和 storage.js 编写 Vitest 单元测试，覆盖所有核心功能。
```
Claude 会生成测试文件并运行：
```bash
npx vitest run
# ✓ tests/storage.test.js (3 tests)
# ✓ tests/todo.test.js (5 tests)
#
# Tests 8 passed (8)
```
---
## 八、新手十大避坑指南
根据社区反馈和实际使用经验，以下是新手最常踩的十个坑：
### 坑 1：不写 CLAUDE.md 就开工
**症状**：Claude 生成的代码风格不统一、不了解项目结构。
**解法**：进入项目后第一件事就是 `/init` 生成 CLAUDE.md。哪怕只有三行——技术栈、常用命令、项目结构——也胜过空白。
### 坑 2：对话太长不压缩
**症状**：到第 30 轮对话时，Claude 开始"遗忘"早期内容，Token 消耗暴增。
**解法**：每完成一个阶段性任务，执行 `/compact`。这会将对话历史压缩为摘要，释放上下文空间。
```mermaid
graph LR
A[新会话开始] --> B[阶段任务1]
B --> C["/compact 压缩"]
C --> D[阶段任务2]
D --> E["/compact 压缩"]
E --> F[阶段任务3]
style C fill:#fff9c4
style E fill:#fff9c4
```
### 坑 3：盲目批准所有操作
**症状**：Claude 执行了 `rm` 或修改了不相关的文件。
**解法**：每次 Claude 请求执行命令时，花 5 秒阅读确认信息。特别关注：
- 是否涉及删除操作
- 是否修改了非目标文件
- 命令参数是否合理
### 坑 4：把 Claude 当搜索引擎
**症状**：问 Claude "什么是闭包"这类通用知识问题，浪费项目上下文。
**解法**：通用知识问 ChatGPT/浏览器，项目相关问题问 Claude Code。Claude Code 的优势在于理解你的代码库。
### 坑 5：一个会话干所有事
**症状**：在一个会话中修 Bug、加功能、重构代码，上下文混乱。
**解法**：一个任务一个会话。完成后 `Ctrl+D` 退出，新任务开新会话。可以通过 `claude --continue` 延续最近的会话。
### 坑 6：忽略 Token 消耗
**症状**：月底账单惊人。
**解法**：定期使用 `/cost` 查看消耗。学会使用 `/compact` 和短会话策略。Sonnet 模型性价比最高，日常开发优先用 Sonnet。
```
/cost
# Session cost: $0.42 (127K input tokens, 3.2K output tokens)
```
### 坑 7：不改就直接用 Claude 的代码
**症状**：Claude 生成的代码能跑但有隐藏问题（安全漏洞、边界情况未处理）。
**解法**：Claude 生成的代码是你的起点而非终点。养成审查习惯：
- 检查输入验证
- 检查错误处理
- 检查安全敏感操作
### 坑 8：在错误目录启动 Claude Code
**症状**：Claude 在 home 目录启动，扫描所有文件，消耗大量 Token。
**解法**：始终在项目根目录启动 `claude`。Claude Code 会读取当前目录及子目录的文件作为上下文。
```bash
# ❌ 错误
cd ~ && claude
# ✅ 正确
cd ~/projects/my-app && claude
```
### 坑 9：不利用 Plan 模式
**症状**：Claude 直接改代码，改完发现方向不对，又要回滚。
**解法**：复杂任务先进入 Plan 模式。Claude 会先分析并输出计划，你确认后再执行。在提示词中加入"先制定计划"或使用 EnterPlanMode 功能。
### 坑 10：忽视 `.gitignore`
**症状**：Claude 读取了 `node_modules`、`dist`、`.env` 等大文件/敏感文件，既浪费 Token 又有安全风险。
**解法**：项目根目录的 `.gitignore` 会自动被 Claude Code 尊重。确保它包含：
```
node_modules/
dist/
.env
.todos.json
*.log
```
---
## 九、进阶提示词技巧
### 9.1 结构化提示词
```
请为 src/auth.js 添加 JWT 认证功能：
需求：
- 登录接口接收用户名和密码
- 验证成功后返回 JWT token
- token 有效期 24 小时
- 包含刷新 token 机制
约束：
- 使用 Node.js 内置 crypto 模块
- 不要引入额外依赖
- 添加错误处理
- 编写对应的单元测试
```
### 9.2 上下文引用
```
@src/index.js 这个文件中的路由配置有问题，
当访问 /api/unknown 时返回 500 而不是 404，
请修复并添加对应的测试。
```
使用 `@` 符号可以引用特定文件，帮助 Claude 精确定位问题。
### 9.3 迭代式开发
```
# 第一轮
请创建一个基本的 Express 服务器，包含健康检查接口
# 第二轮（在 Claude 完成后）
添加用户 CRUD 接口，使用内存数组暂存数据
# 第三轮
将数据存储从内存数组切换到 JSON 文件持久化
# 第四轮
为所有接口编写集成测试
```
这种渐进式方式比一次性描述所有需求更高效，每一步都可以验证。
---
## 十、完整工作流程图
```mermaid
flowchart TB
subgraph 准备阶段
A[安装 Node.js + npm] --> B[npm install -g @anthropic-ai/claude-code]
B --> C[配置认证：API Key 或 OAuth]
end
subgraph 项目初始化
C --> D[cd my-project && git init]
D --> E[claude 启动]
E --> F["/init 生成 CLAUDE.md"]
F --> G[审查并修改 CLAUDE.md]
end
subgraph 开发循环
G --> H[描述需求]
H --> I{Claude 生成方案}
I --> J[审查方案]
J -->|不满意| K[调整提示词]
K --> H
J -->|满意| L[确认代码变更]
L --> M[运行测试验证]
M -->|测试失败| N[告诉 Claude 修复]
N --> H
M -->|测试通过| O["/compact 压缩上下文"]
O --> P{还有新任务?}
P -->|有| H
P -->|无| Q["/cost 检查消耗"]
end
subgraph 收尾
Q --> R[git commit 提交]
R --> S[Ctrl+D 退出]
end
style A fill:#e3f2fd
style F fill:#fff3e0
style O fill:#e8f5e9
style R fill:#fce4ec
```
---
## 十一、常见问题排查
### Q1：安装时报 `EACCES` 权限错误
```bash
# 原因：npm 全局目录权限不足
# 解法：使用 nvm 管理 Node.js，避免 sudo
nvm install 20
npm install -g @anthropic-ai/claude-code
```
### Q2：启动后提示"无法连接到 API"
```bash
# 检查网络连接
curl -I https://api.anthropic.com
# 如果在国内，需要配置代理
export HTTPS_PROXY=http://your-proxy:port
# 或使用国内 API 代理服务
export ANTHROPIC_BASE_URL=https://your-proxy.com/v1
```
### Q3：Claude 总是生成不符合项目风格的代码
检查你的 CLAUDE.md 是否包含：
1. 明确的技术栈版本
2. 具体的编码规范
3. 项目结构说明
4. "不要做"的清单（如"不要安装额外依赖"）
### Q4：VS Code 扩展无法启动
```bash
# 1. 确认 CLI 可用
claude --version
# 2. 重新安装扩展
# VS Code → 扩展 → 搜索 Claude Code → 卸载 → 重装
# 3. 检查输出面板
# 查看 → 输出 → 选择 Claude Code 查看日志
```
---
## 十二、下一步学习路径
完成本文教程后，建议按以下顺序深入学习：
```mermaid
graph TD
A[✅ 本文：入门安装与首个项目] --> B[Skill 开发实战]
A --> C[CLAUDE.md 六层配置]
A --> D[Token 成本优化]
B --> E[MCP 服务器开发]
C --> F[多 Agent 并行编排]
D --> G[CI/CD 自动化集成]
E --> H[企业级工具链构建]
```
| 路径 | 核心内容 | 预计学习时间 |
|------|---------|-------------|
| Skill 开发 | 自定义能力扩展 | 2-3 小时 |
| 配置深度 | CLAUDE.md 高级配置 | 1-2 小时 |
| Token 优化 | 成本控制策略 | 1 小时 |
| MCP 开发 | 外部工具集成 | 3-4 小时 |
| Agent 编排 | 并行与自动化 | 2-3 小时 |
---
## 参考来源
1. [Quickstart - Claude Code 官方文档](https://code.claude.com/docs/en/quickstart) — Anthropic 官方快速入门指南，涵盖安装、认证和基本使用
2. [Claude Code Tutorial for Beginners - Complete 2026 Guide](https://codewithmukesh.com/blog/claude-code-for-beginners/) — CodeWithMukesh 出品的完整初学者教程，覆盖从安装到构建首个项目
3. [Complete Beginner's Guide to Claude Code 2026](https://claudecode-lab.com/en/blog/claude-code-getting-started-complete/) — Claude Code Lab 的七步入门指南，从零到集成开发环境
4. [10 Common Claude Code Mistakes](https://claude-world.com/articles/common-beginner-mistakes/) — 社区总结的十大常见错误及修复方法
5. [Claude Code 完整指南：安装、CLI 实战、IDE 集成](https://blog.csdn.net/qq_20042935/article/details/156649482) — CSDN 中文深度指南，涵盖 Windows/Mac/Linux 全平台
---
> **训练营适用性评估**：
> - **适合类型**：AI 编程工具入门训练营、企业内部 Claude Code 推广培训、高校 AI 辅助编程课程
> - **教学时长**：3-4 小时（含实操），可拆分为两次 2 小时课程
> - **前置要求**：基础命令行操作能力，了解任意一门编程语言
> - **硬件要求**：每人一台笔记本电脑，联网环境
> [!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 等场景全覆盖。
