Claude Code 实用教程：Windows、macOS、Linux 从安装到项目调试与验收

第一次使用 Claude Code，不必先收集几十个插件。先完成一个小任务：让它读取项目约定、实现一个函数、运行你能理解的测试，再根据失败输入修复问题。做到这一步，安装才真正变成了可用的工作流程。

本文以终端 CLI 为主，按三种系统给出入口，再用离线 CSV 校验练习串起配置、提问、调试和验收。文档核查日期为 2026-09-17。本轮没有安装或运行 Claude Code 会话；示例 Python 程序与测试在 macOS / arm64、Python 3.12.14 实际运行，不代表 Claude Code 在三系统已实测或某模型必然产出同样结果。

一、按系统安装，先分清终端

以下为 2026-09-17 核查的官方安装步骤，不是三个系统的逐台安装实测。

Windows 原生，PowerShell：

powershell 复制代码

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

若使用 WinGet，可选 winget install Anthropic.ClaudeCode；升级用 winget upgrade Anthropic.ClaudeCode。两种方式选一种，减少 PATH 指向旧安装的混淆。

当前文档允许原生 Windows 运行；Git for Windows 可提供 Git Bash，未安装时使用 PowerShell 工具。项目要用 Git 命令，仍需安装 Git。不要把"启动 Claude Code"与"具备项目所需工具链"混为一谈。

macOS，终端：

bash 复制代码

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

Linux，终端： 使用相同的 shell 安装器。若使用 Alpine 等环境，先按官方文档核对额外系统依赖，不能把 Ubuntu 的包管理命令直接复制过去。原生安装器与 Homebrew、WinGet 的更新机制不同；包管理器安装要用对应升级命令。

Windows + WSL2： 进入 WSL 的 Linux 终端，再执行 Linux 安装步骤。原生 Windows 与 WSL 是可选路线，不要把 PowerShell 的 irm 命令粘贴到 bash。需要 Linux 工具链或对应沙箱能力时，再考虑 WSL2；原生 Windows 与 WSL2 的沙箱支持并不相同。系统与平台差异

二、登录并确认项目范围

进入项目目录后输入 claude，按首次提示完成登录。在已启动的会话里，/login 可重新认证，/help 查看命令。官方支持 Claude 订阅、Console 等认证路线，实际账户资格与计费以登录页面为准；已有 ANTHROPIC_API_KEY 环境变量可能改变登录流程。快速开始

不需要为了入门先购买最高档套餐或第三方共享账号。先明确当前账户用哪种方式计费、剩余额度在哪里看，再做一次小范围练习。不要把真实密钥贴给模型或写进 CLAUDE.md。

启动目录应是练习项目，不是整个用户主目录。先发"请说明当前工作目录和现有文件，暂不修改"，确认看到的范围符合预期。

三、用 CLAUDE.md 留下项目约定

在项目根目录保存 CLAUDE.md：

text 复制代码

这是离线 CSV 校验练习，只处理本目录的合成数据。
使用 Python 标准库，不引入第三方依赖。
字段必须为 sku,price；SKU 去掉首尾空白后非空且唯一。
价格用 Decimal，必须为有限非负数；表头-only 文件返回零条。
修改后运行 python3 -m unittest -v，并报告实际退出状态。
不改原始 CSV，不访问真实业务服务，不提交或推送代码。

这里的 python3 适用于本例 macOS/Linux 命令；Windows 根据实际运行时改成 py -3。文件中应写可验证的命令和约束，而不是"代码质量一定要高"这种无法验收的话。

也可以用 /init 生成初稿，再删掉重复或不适用的内容。/context 可检查加载的记忆文件。Claude Code 默认读取 CLAUDE.md；若项目已用 AGENTS.md，可通过 CLAUDE.md 中的 @AGENTS.md 导入共享约定，不要假设两个文件名天然等价。项目记忆文档

四、先给样本与验收，再让它实现

新建 prices.csv，内容为：

csv 复制代码

sku,price
A,0.10
B,0.20

期望输出为 {"count": 2, "total": "0.30"}。在 Claude Code 里提出具体任务：

text 复制代码

请实现 check_prices.py：读取 UTF-8 CSV，表头为 sku,price。
验证 SKU 非空、不重复，价格为有限非负十进制数。
成功输出 JSON，包含 count 和字符串形式的 total；错误输入报错并非零退出。
只使用 Python 标准库，不修改输入文件。
给出 unittest 测试，覆盖正常求和、只有表头、错误表头、重复 SKU、
空 SKU、非法/负数/NaN/Infinity 价格、缺列/多列和中文 SKU。
先说明输入输出与需要创建的文件，再实施。最后实际运行测试并报告结果。

计划阶段可以先要求解释文件和测试设计，或者按当前会话提供的 Plan 模式入口操作。确认方案覆盖输入错误后，再让它实施。不要照搬旧教程中"默认一定逐步确认"的说法；起始权限模式受版本、套餐与组织设置影响，先检查当前显示的模式。权限文档

五、验收不要只盯正常样本

生成 check_prices.py 与 test_prices.py 后，在项目目录运行：

bash 复制代码

python3 check_prices.py prices.csv
python3 -m unittest -v

Windows 的 Python 启动器版本：

powershell 复制代码

py -3 check_prices.py prices.csv
py -3 -m unittest -v

按下面清单检查测试内容：

输入	期望
A=0.10、B=0.20	2 条，合计字符串 0.30
只有 sku,price 表头	0 条，总额 0
表头写成 sku,cost	拒绝
A 与带空白的 A	拒绝重复 SKU
SKU 为空或只有空白	拒绝
空价格、abc、负数、NaN、Infinity	拒绝
缺列或多列	拒绝
中文 SKU，价格 0	接受

本文准备的参考程序已在 macOS 下通过对应的 8 个 unittest 方法；这是练习代码的验证，不能当成 Claude Code 的模型测评。代码实现允许普通十进制价格，生产环境仍需补金额上限、小数位数、精度和文件大小约束。

六、出错时，提供能复现的材料

例如重复 SKU 没被拦住，可以这样继续：

"prices.csv 的两行 SKU 分别为 A 与空格 A 空格，当前仍输出成功。业务约定是去首尾空白后判重。请先新增失败测试，修复最小范围，再运行全部测试；不要把第二行悄悄去掉。"

这段反馈同时给了输入、观察、业务规则和不接受的修复方式。若只是说"结果不对"，模型可能通过跳过错误数据让程序看似成功。

检查最终修改时，同时看 git diff 和 git status --short；新文件不一定出现在普通 diff 中。确认实现与测试后再决定是否提交。不要为了撤销一次小改动就直接清空整个工作目录。

七、排障和下一次接续

找不到 claude 时先重开终端，核对 PATH；Windows 使用 Get-Command claude，macOS/Linux 使用 command -v claude。能够启动但配置异常，可用 /doctor；完全启动不了时用终端命令 claude doctor。排障入口

Windows 的 PowerShell、CMD 和 WSL bash 语法不同，出现 irm 或 && 相关错误先确认终端。登录异常、网络异常与项目测试失败也要分开处理，重装并不能解决所有问题。

同一个任务下次用 claude --continue 接续最近会话，或者 claude --resume 选择历史会话。需要重复保存的是项目约定、输入样本和检查方法；不要只依赖聊天里一句"上次已经做好"。会话命令