本教程面向零基础开发者，从安装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概念（可选，但推荐） - 了解任意一门编程语言的基础语法
Claude Code是一个Node.js包，通过npm安装。如果你已经安装了Node.js 18+，可以跳过此步。
推荐使用 nvm（Node Version Manager）管理Node.js版本：
# 安装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 或更高
# 使用NodeSource仓库安装
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
# 验证
node --version
npm --version
Windows用户需要先启用WSL2（Windows Subsystem for Linux），然后在WSL2中按Linux方式操作：
# 在PowerShell管理员模式中安装WSL2
wsl --install
# 重启后，打开Ubuntu终端，按上述Linux步骤安装Node.js
常见问题：如果
node --version显示版本低于18，请使用nvm切换到较新版本。Claude Code严格要求Node.js >= 18。
npm install -g @anthropic-ai/claude-code
安装完成后验证：
claude --version
# 输出示例: 2.1.56 (Claude Code)
Claude Code支持两种认证方式：
方式一：OAuth登录（推荐，适用于Anthropic订阅用户）
claude auth
执行后会自动打开浏览器，跳转到Anthropic登录页面。完成授权后，终端会显示登录成功信息。
验证登录状态：
claude auth status
# 输出: loggedIn: true, authMethod: oauth_token, apiProvider: firstParty
方式二：API Key认证（适用于API用户）
# 设置环境变量
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：
claude setup-token
这会引导你创建一个持久化的认证Token，存储在本地配置中。
在开始编码前，让我们先理解Claude Code的几个核心概念。这些概念将贯穿你的整个使用过程。
图表 1
Claude Code有两种主要运行模式：
| 模式 | 命令 | 适用场景 |
|---|---|---|
| 交互式 | claude |
日常开发、对话式编程 |
| 管道模式 | claude -p "prompt" |
脚本集成、CI/CD、批量任务 |
交互式模式是你的主要工作模式。启动后会进入一个对话界面，你可以用自然语言描述需求，Claude Code会自动选择合适的工具来完成任务。
管道模式适合自动化场景，输出结果后立即退出，可以与其他命令行工具配合使用：
# 示例：让Claude Code解释当前目录的代码结构
claude -p "列出这个项目的目录结构并简要说明"
# 示例：结合其他命令使用
echo "这个函数做了什么？" | claude -p
Claude Code内置了多种工具，它会在对话中自动选择合适的工具：
**/*.ts）你不需要手动调用这些工具——Claude Code会根据你的自然语言描述自动选择。但了解它们的存在有助于你更好地描述需求。
Claude Code的权限系统保护你的安全。每当Claude Code想要执行敏感操作（如修改文件、运行命令），它会先请求你的确认：
Claude wants to edit file: src/index.ts
Allow? (y/n)
你可以通过配置来管理权限，减少重复确认。权限模式包括：
| 模式 | 说明 |
|---|---|
default |
默认模式，敏感操作需确认 |
acceptEdits |
自动接受文件编辑，命令仍需确认 |
plan |
只规划不执行，适合审查方案 |
bypassPermissions |
跳过所有权限检查（仅限沙箱环境） |
现在让我们用Claude Code从零开始创建一个待办事项（Todo）命令行应用。
# 创建项目目录
mkdir my-first-claude-project
cd my-first-claude-project
# 初始化Git仓库
git init
# 启动Claude Code
claude
启动Claude Code后，首次运行它会引导你创建 CLAUDE.md 文件。你也可以手动创建：
# 项目：命令行待办事项应用
## 技术栈
- 语言：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.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会逐个创建文件）：
# 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
# 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
# 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 <ID> 标记任务完成")
print(" delete <ID> 删除任务")
if __name__ == "__main__":
main()
让Claude Code帮你测试，或手动运行：
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的日常使用命令。
# 启动交互式会话（在项目目录中）
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 |
# 在启动时指定模型
claude --model sonnet # 快速高效
claude --model opus # 最强推理能力
# 在会话中切换
> /model
# 会显示可用模型列表供选择
Claude Code支持控制"努力程度"，影响回答的深度和长度：
# 低努力 - 快速回答，适合简单问题
claude --effort low
# 中等努力 - 平衡模式（默认）
claude --effort medium
# 高努力 - 深度思考，适合复杂任务
claude --effort high
Claude Code的配置文件位于 ~/.claude/settings.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：
{
"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模式
claude --permission-mode plan
# 或在会话中让Claude Code先规划
> 请先规划一下如何重构这个应用，不要直接修改代码
Plan模式下Claude Code只会分析和规划，不会执行任何文件修改或命令运行。确认方案后再切换回正常模式执行。
图表 2
Claude Code与Git深度集成，让版本控制变得轻松。
# 让Claude Code查看当前状态
> 查看当前的git状态和最近的改动
# 让Claude Code帮你提交
> 请帮我提交当前的改动，写一个清晰的commit message
# 代码审查
> /review
# Claude Code会分析所有未提交的改动并给出建议
# 创建分支
> 请创建一个feature/add-search分支，并切换过去
当你需要同时处理多个任务时，Worktree功能让你在不同分支上并行工作：
# 在新的worktree中启动Claude Code
claude --worktree feature-add-search
# 这会自动创建一个新的git worktree和分支
# Claude Code在其中独立工作，不会影响主分支
# 完成后，回到主目录合并
git merge feature-add-search
让我们在刚才的基础上增强Todo应用，体验完整的Claude Code开发工作流。
> 请在现有Todo应用基础上添加以下功能：
> 1. 搜索功能 - 支持按标题关键词搜索
> 2. 优先级 - 支持设置高/中/低优先级，列表按优先级排序
> 3. 标签系统 - 支持给任务添加标签，按标签筛选
> 4. 彩色输出 - 使用ANSI颜色码美化终端输出
Claude Code会先分析现有代码，然后给出修改方案。审查时注意： - 改动是否影响现有功能 - 数据迁移是否需要（JSON格式变化） - 新增依赖是否合理
> 搜索功能还需要支持模糊匹配，比如"claude"能匹配到"学习Claude Code"
>
> 另外，添加任务时如果没有指定优先级，默认为"中"
> 请运行以下测试：添加5个不同优先级的任务，搜索其中一个，完成一个，删除一个，然后列出所有任务
> 确认功能正常后，帮我提交代码
# 错误信息
npm ERR! Error: EACCES: permission denied
# 解决方案：不要使用sudo安装npm包，改用nvm管理Node.js
npm install -g @anthropic-ai/claude-code
# 检查认证状态
claude auth status
# 重新登录
claude auth
# 如果使用API Key，检查环境变量
echo $ANTHROPIC_API_KEY
当项目很大或对话很长时，可能遇到上下文窗口不足：
# 在会话中使用 /compact 压缩历史
> /compact
# 或启动新会话但保留项目上下文
> /clear
# 使用 --add-dir 添加额外目录
claude --add-dir ../shared-lib
Claude Code有完善的撤销机制：
git diff 查看变更，git checkout -- <file> 撤销git checkout -- <file> 恢复最佳实践：频繁使用
git commit。每次Claude Code完成一个有意义的改动后，手动提交，这样总有回退点。
# 使用更快的模型
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 "关键词" |
找回历史会话 |
| 维度 | 评估 |
|---|---|
| 适合训练营类型 | 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 等场景全覆盖。
