Claude Code 初学者教程：2026年完整指南

前提条件

在开始使用 Claude Code 之前，请确认你已具备以下条件：

• 操作系统：macOS、Linux，或搭载 PowerShell 的 Windows 10+
• Claude 账户：免费账户或已开启 API 访问权限的 Pro/Max 账户
• 终端基础：对命令行界面有基本了解
• 网络连接：认证和 API 调用均需联网

什么是 Claude Code？

Claude Code 是 Anthropic 为 Claude 打造的命令行界面（CLI），让开发者能够完全通过自然语言来编写、重构和调试代码。与传统 IDE 不同，Claude Code 直接在终端中运行，能够自主执行指令、规划多步骤任务，并持续迭代直到完成目标。

与竞品的核心差异

Claude Code vs Cursor vs GitHub Copilot：Cursor 是在 VS Code 基础上叠加 AI 能力的 IDE 封装工具；GitHub Copilot 是编辑器内的代码自动补全插件；而 Claude Code 是一个独立的 CLI 代理，能够自主管理整个项目，做出架构层面的决策，处理那些手动操作往往需要数小时的复杂重构任务。

第一步：在你的系统上安装 Claude Code

安装过程简单，各平台均只需 2-3 分钟。

macOS 和 Linux 安装

打开终端并运行：

curl -fsSL https://claude.ai/install.sh | bash

安装完成后，关闭并重新打开终端，或执行：

source ~/.bashrc

验证安装是否成功：

claude --version

预期输出：Claude CLI version 1.2.0 (or higher)

Windows PowerShell 安装

以管理员身份打开 PowerShell 并运行：

irm https://claude.ai/install.ps1 | iex

如果遇到执行策略错误，先运行以下命令，再重新执行安装：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Windows 备选方案：使用 WinGet 可自动处理权限问题：

winget install Anthropic.ClaudeCLI

第二步：完成 Claude 账户认证

Claude Code 采用基于浏览器的认证方式，安全可靠，不会在本地存储任何 API 密钥。

首次配置流程

1. 在终端运行：claude
2. 默认浏览器会自动打开认证页面
3. 用你的 Claude 账户登录（与 Claude.ai 使用同一邮箱）
4. 按提示授予相应权限
5. 返回终端，看到确认信息即表示认证成功

小贴士：认证状态跨会话持久保存，除非你主动退出登录，否则只需操作一次。

第三步：创建 CLAUDE.md 配置文件

CLAUDE.md 是 Claude Code 的项目说明书，用于定义项目结构、构建流程和代码规范。

生成初始配置

进入项目目录并运行：

cd my-project
claude /init

这会生成一个包含以下模块的 CLAUDE.md 文件：

• 项目概述：简要描述项目目的
• 架构说明：目录结构与核心依赖
• 构建命令：编译和运行项目的方式
• 代码规范：命名约定、格式要求
• 忽略文件：需要排除的路径模式（如 .git、node_modules 等）

自定义你的 CLAUDE.md

以 Python 项目为例：

# Project Overview
Flask REST API for task management

## Architecture
- app.py (main entry point)
- models/ (SQLAlchemy models)
- routes/ (API endpoints)
- tests/ (pytest unit tests)

## Build Commands
- pip install -r requirements.txt
- python app.py

## Code Style
- PEP 8 compliance
- Type hints required
- Docstrings for all functions

## Ignored Files
__pycache__/
venv/
*.pyc
.env

第四步：掌握核心命令与快捷键

以下命令用于控制你的 Claude Code 会话：

核心命令

• /help — 显示可用命令列表
• /clear — 清除对话历史
• /cost — 查看 API 用量和预估费用
• /status — 查看当前项目上下文
• /exit — 安全退出会话

快捷键

• Tab — 自动补全文件名和命令
• @文件名 — 在消息中直接引用指定文件
• ! — 直接执行 Shell 命令（如 !npm test）
• Ctrl+C — 取消当前操作
• ↑/↓ — 浏览命令历史

第五步：用 Claude Code 构建你的第一个项目

现在用自然语言从零开始创建一个实际项目。

创建项目目录

mkdir claude-weather-app
cd claude-weather-app
claude

用自然语言描述需求

直接用中文或英文描述你想要的项目：

Create a Python command-line weather app that:
1. Takes a city name as input
2. Fetches current weather data from a free API
3. Displays temperature, humidity, and conditions
4. Has error handling for invalid cities
5. Includes unit tests using pytest

接下来会发生什么：

1. Claude 分析你的需求并制定项目计划
2. 生成所需文件（主程序、requirements.txt、测试文件）
3. 展示变更差异（diff）供你审查
4. 等待你确认：输入 yes 接受，输入 no 修改
5. 持续迭代直到项目完整可运行

审查差异并提出修改

在确认前务必仔细阅读 Claude 的提案：

--- app.py (new file)
+++ app.py
@@ -1,0 +1,25 @@
+import requests
+from typing import Dict
+
+def get_weather(city: str) -> Dict[str, str]:
+    """Fetch weather data for a given city."""
+    ...

[Diff continues]

Accept these changes? (yes/no)

如果对某处变更有异议，直接用自然语言说明：

no, use the weather.gov API instead and include wind speed

Claude Code 最佳实践

1. 需求描述要具体

❌ 模糊："做一个 Web 应用"

✅ 具体："用 FastAPI + PostgreSQL 创建一个博客 REST API，包含 JWT 用户认证、文章 CRUD 操作和错误处理。"

2. 善用 @文件 语法

处理已有代码时，直接引用文件：

@models.py add pagination to the User query

3. 用 /cost 监控用量

Claude Code 的使用会计入 API 用量：

/cost
Current session: $2.34
Today: $12.50
Monthly limit: $100

4. 定期提交代码

用 Git 追踪 Claude 的每次修改：

git add .
git commit -m "Claude Code: Add authentication system"

常见误区与规避方法

误区一：项目上下文不完整

问题：没有配置 CLAUDE.md，导致 Claude 做出错误的架构决策。

解决：在执行复杂任务前，务必先运行 claude /init 并完善配置文件。

误区二：不审查就直接接受变更

问题：盲目接受每一个 diff，可能引入安全漏洞或导致应用崩溃。

解决：每次都要仔细阅读差异，尤其是涉及认证等安全敏感区域的改动。

误区三：需求描述过于模糊

问题：让 Claude "修复整个应用"这类宽泛请求，既浪费 API 额度，效果也差强人意。

解决：将大任务拆解为小而明确的子任务，每个任务都有清晰的完成标准。

误区四：忽视错误信息

问题：Claude 给出了有用的错误提示，但用户直接忽略，重复执行同一命令。

解决：认真阅读错误信息，根据提示调整你的请求。

故障排查指南

问题：出现"Authentication Failed"错误

解决方案：

claude /logout
claude /login
# 重新完成浏览器认证流程

问题：Claude 做出了错误的架构决策

解决方案：在 CLAUDE.md 中补充明确的架构约束，然后用更新后的配置重新执行命令。

问题：简单任务消耗了过多 API 费用

解决方案：在不相关的任务之间使用 /clear 清除上下文，用 /cost 实时监控用量。

Claude Pro vs Claude Max：编程场景对比

Claude Pro（20美元/月）：适合轻度编程需求（每周1-2个项目），速率限制为每分钟40次 API 调用。

Claude Max 5x（100美元/月）：面向全职开发者，用量是 Pro 的5倍，针对大型代码库优化。

Claude Max 20x（200美元/月）：面向重度用户和商业开发团队，用量是 Pro 的20倍。

进阶功能

在 Claude Code 中执行 Shell 命令

直接运行系统命令：

!npm test
!python -m pytest
!docker build .

机器学习项目支持

Claude Code 能很好地处理 ML 项目：

• 生成数据预处理脚本
• 编写模型训练代码
• 实现评估指标
• 注意：无法直接可视化图表，需要单独运行 Jupyter Notebook 进行可视化。

多文件项目管理

Claude Code 擅长管理具有复杂依赖关系的大型项目，只需指向主文件或目录即可：

claude
I need to refactor the entire authentication system in this codebase.
@auth/ @models/ @utils/ - review these and suggest improvements.

参考文献

• Claude 官方网站
• Claude GitHub 仓库
• Anthropic 官方文档
• Python 下载
• PowerShell 文档