## 概述 本教程带你从零完成 Claude Code 的安装、首次认证、基础配置，并用一个真实可运行的项目——命令行单位换算器（温度、长度、重量互转）——把"装好→配好→跑起来"这条主线彻底走通。读完你将：理解 Claude Code 在终端里的工作方式；独立完成 Node.js 环境检查与全局安装；用订阅账号或 API Key 完成认证；写出自己的 `CLAUDE.md` 与 `settings.json`；掌握高频斜杠命令；并能用自然语言指挥 Claude 从零生成一个带测试的小工具。适用人群：从未用过 AI 命令行编程工具、想第一次就把环境装顺、装对的开发者。 ## 前置条件 - 一台 macOS、Linux 或 Windows（建议 Windows 用户使用 WSL2）电脑，能稳定联网。 - 终端基础：会 `cd` 进目录、会 `mkdir` 建文件夹即可，**不需要**事先会写代码——这正是让 Claude 写。 - 一个 Claude 账号：要么是 Claude Pro / Max 订阅（推荐新手，开通后无需单独计费），要么是一把 Anthropic API Key（按用量计费）。 - Node.js 18 及以上版本（Claude Code 以 npm 全局包形式分发）。 --- ## 第一步：先搞清楚 Claude Code 是什么 Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手。它不是网页版聊天框，而是一个跑在你终端里、**能真正读你的文件、改你的代码、执行命令、跑测试**的智能体。你在项目目录里输入 `claude` 进入交互界面，用自然语言下达任务（"帮我写一个温度换算工具并加测试"），它就会读写文件、运行命令、把结果交还给你确认。 它的几条核心能力，决定了入门教程的顺序： - **文件读写**：能看懂你的项目结构，直接新建/修改文件。 - **命令执行**：能跑 `python`、`pytest`、`git` 等命令并把输出喂回给自己。 - **记忆系统**：通过 `CLAUDE.md` 把"项目规矩"长期记住。 - **权限分级**：默认每次危险操作都征求你同意，安全可控。 理解了这四点，后面每一步配置你都会知道"为什么这么设"。 ## 第二步：准备 Node.js 环境 Claude Code 是一个 npm 全局包，先确认 Node 版本达标（≥ 18）。 打开终端，执行： ```bash node -v npm -v ``` 预期结果类似： ``` v20.17.0 10.8.2 ``` 常见问题与解决： - **命令找不到（`command not found: node`）**：说明没装 Node。macOS 推荐 `brew install node`；Windows/WSL 推荐 [nvm](https://github.com/nvm-sh/nvm) 安装：`nvm install --lts`。 - **版本低于 18**：用 nvm 升级 `nvm install 20 && nvm use 20`，或到官网下载 LTS 安装包。 - **公司网络拉不到包**：配置 npm 镜像，`npm config set registry https://registry.npmmirror.com`（仅影响 npm 下载速度，不影响 Claude 本身）。 ## 第三步：安装 Claude Code 一条命令全局安装： ```bash npm install -g @anthropic-ai/claude-code ``` 验证安装成功： ```bash claude --version ``` 预期输出形如 `2.x.x` 的版本号。看到版本号就说明可执行文件已经在 `PATH` 里了。 常见问题与解决： - **`EACCES: permission denied`**：权限不足。要么加 `sudo`（不推荐，全局包权限混乱），要么把 npm 全局目录改到用户目录下：`npm config set prefix ~/.npm-global`，再把 `$HOME/.npm-global/bin` 加进 `PATH`。 - **安装很慢或超时**：见上一步的镜像配置；或挂代理后重试。 - **Windows 提示脚本无法执行**：在 PowerShell 以管理员运行 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`，或直接用 WSL。 ## 第四步：首次启动与认证 进入你打算放代码的目录，启动交互界面： ```bash mkdir ~/projects && cd ~/projects claude ``` 第一次启动会要求你**认证**，有两条路： **路线 A：订阅账号登录（Pro / Max，推荐新手）** 选择浏览器登录后，终端会显示一个网址和一串验证码，自动打开浏览器，确认后回到终端，提示已登录。此后在订阅额度内使用，无需管 API Key。 **路线 B：API Key 计费** 到 [Anthropic Console](https://console.anthropic.com/) 创建一把 Key，然后两种方式二选一： ```bash # 方式一：写进 shell 配置（推荐，长期生效） echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.zshrc # bash 用户改 ~/.bashrc source ~/.zshrc # 方式二：仅在当前会话临时设置 export ANTHROPIC_API_KEY="sk-ant-xxxxx" ``` 再运行 `claude` 即可。 常见问题与解决： - **浏览器没自动弹出**：手动复制终端里那串网址到浏览器打开即可。 - **登录后仍提示无权限 / 401**：多半是 API Key 复制时带了空格或换行，重新设置一次。 - **公司代理拦截 OAuth 回调**：改用 API Key 路线更稳。 - **安全提醒**：无论哪种方式，都**不要**把 Key 写进会提交到 GitHub 的文件里，下文的 `settings.local.json` 就是为隔离敏感配置准备的。 ## 第五步：配置 `settings.json` 与 `CLAUDE.md` 装好不等于配好。Claude Code 的配置分两块，一块管"行为开关"，一块管"项目规矩"。 ### 5.1 `settings.json`：行为与权限 Claude Code 按优先级读取三层配置： | 文件 | 作用域 | 是否进版本库 | |------|--------|--------------| | `~/.claude/settings.json` | 全局，所有项目生效 | 否（个人偏好） | | `项目/.claude/settings.json` | 团队共享 | 是 | | `项目/.claude/settings.local.json` | 本机个人覆盖 | 否（含密钥/本机路径） | 一个稳妥的入门全局配置示例 `~/.claude/settings.json`： ```json { "model": "claude-sonnet-4-6", "permissions": { "allow": [ "Bash(npm run test:*)", "Bash(python:*)", "Read(**)", "Edit(**)" ], "deny": [ "Bash(rm -rf:*)", "Read(./.env)", "Read(./**/*.pem)" ] }, "env": { "HTTP_PROXY": "http://127.0.0.1:7890" } } ``` 要点： - `model` 指定默认模型；需要更强推理时可用 `claude-opus-4-8`，要省钱省速用 `claude-haiku-4-5`。 - `allow` 把那些"反复点同意很烦但又安全"的只读/测试命令放行，减少打断。 - `deny` 兜底拦危险操作——即便你不在场，也删不掉整盘、读不到密钥文件。 你也可以在交互界面里输入 `/config` 用可视化方式改这些项。 ### 5.2 `CLAUDE.md`：项目记忆 `CLAUDE.md` 是给 Claude 看的"项目说明书"。最省事的生成方式：在项目根目录运行： ```bash claude > /init ``` Claude 会扫描项目结构、自动生成一份 `CLAUDE.md` 初稿，你再手动润色。对本教程的换算器项目，目标 `CLAUDE.md` 长这样： ```markdown # 项目：命令行单位换算器 ## 目标 一个零依赖的 Python 命令行工具，支持温度、长度、重量三类单位互转。 ## 运行方式 - 运行：`python converter.py --from C --to F 100` - 测试：`python -m pytest test_converter.py -v` ## 代码规范 - 只用 Python 标准库，不引入第三方依赖。 - 所有公共函数写中文 docstring。 - 数值换算保留 4 位小数。 - 温度换算与线性换算区分处理。 ## 目录结构 - converter.py：核心逻辑与 CLI 入口 - test_converter.py：单元测试 ``` `CLAUDE.md` 的记忆是**分层**的：企业级 > 用户级（`~/.claude/CLAUDE.md`）> 项目根目录 > 子目录。越靠近文件，优先级越高，所以你可以在不同子目录放不同规矩。 ## 第六步：高频斜杠命令速览 进入交互界面后，这些命令是日常： | 命令 | 作用 | |------|------| | `/help` | 查看全部命令 | | `/init` | 扫描项目并生成 `CLAUDE.md` | | `/config` | 可视化修改设置 | | `/model` | 切换 Opus / Sonnet / Haiku | | `/clear` | 清空当前对话上下文（换任务前必用） | | `/compact` | 压缩上下文，长会话省额度 | | `/cost` | 看本次会话花了多少 token / 钱 | | `/review` | 让 Claude 审一遍当前改动 | | `/agents` | 管理子代理 | | `/mcp` | 管理 MCP 外部工具 | 另外有四个权限模式值得关注，按"放手程度"递增：默认（每次确认）→ `acceptEdits`（自动接受文件编辑）→ Plan 模式（只规划不动手，按 `Shift+Tab` 切换）→ `bypassPermissions`（全自动，慎用）。新手请老老实实待在默认模式。 ## 第七步：第一个项目——命令行单位换算器（实战） 现在把前面全部串起来，亲手造一个工具。 ### 7.1 建项目骨架 ```bash mkdir -p ~/projects/unit-converter && cd ~/projects/unit-converter # 把第五步那段 CLAUDE.md 内容存成项目根目录的 CLAUDE.md claude ``` ### 7.2 给 Claude 的提示词 进入交互界面后，先建任务清单，再让它动手。把下面这段直接发给它： ``` 请阅读 CLAUDE.md，然后帮我实现这个命令行单位换算器，分两步： 1. 先用 TodoWrite 列出任务清单（实现核心库、实现 CLI、写测试、跑测试）。 2. 按清单逐步实现 converter.py 与 test_converter.py，每写完一块就用 python -m pytest 跑一遍测试，全部通过再交付。 要求： - 温度：C(摄氏) ↔ F(华氏) ↔ K(开尔文) - 长度：m / km / cm / mile / foot / inch - 重量：g / kg / t / lb / oz - 命令行用 argparse，支持 --from/--to/数值 三个参数。 ``` ### 7.3 预期结果 Claude 会先生成 `converter.py`，核心逻辑大致如下（它会按你的 CLAUDE.md 规范来写）： ```python import argparse # 各单位到基准单位的换算因子（温度单独处理） LENGTH_TO_METER = { "m": 1.0, "km": 1000.0, "cm": 0.01, "mile": 1609.344, "foot": 0.3048, "inch": 0.0254, } WEIGHT_TO_GRAM = { "g": 1.0, "kg": 1000.0, "t": 1_000_000.0, "lb": 453.59237, "oz": 28.349523125, } def convert_length(value, src, dst): """把 value 从 src 长度单位换算到 dst，保留 4 位小数。""" if src not in LENGTH_TO_METER or dst not in LENGTH_TO_METER: raise ValueError(f"不支持的长度单位: {src} 或 {dst}") meters = value * LENGTH_TO_METER[src] return round(meters / LENGTH_TO_METER[dst], 4) def convert_weight(value, src, dst): """把 value 从 src 重量单位换算到 dst，保留 4 位小数。""" if src not in WEIGHT_TO_GRAM or dst not in WEIGHT_TO_GRAM: raise ValueError(f"不支持的重量单位: {src} 或 {dst}") grams = value * WEIGHT_TO_GRAM[src] return round(grams / WEIGHT_TO_GRAM[dst], 4) def convert_temperature(value, src, dst): """温度换算：在摄氏、华氏、开尔文之间互转。""" table = {"C", "F", "K"} if src not in table or dst not in table: raise ValueError(f"不支持的温度单位: {src} 或 {dst}") # 先统一到摄氏 if src == "F": c = (value - 32) * 5 / 9 elif src == "K": c = value - 273.15 else: c = value # 再从摄氏到目标 if dst == "F": return round(c * 9 / 5 + 32, 4) if dst == "K": return round(c + 273.15, 4) return round(c, 4) def main(): p = argparse.ArgumentParser(description="命令行单位换算器") p.add_argument("--from", dest="src", required=True, help="源单位") p.add_argument("--to", dest="dst", required=True, help="目标单位") p.add_argument("value", type=float, help="待换算的数值") args = p.parse_args() src, dst = args.src, args.dst if src in LENGTH_TO_METER and dst in LENGTH_TO_METER: result = convert_length(args.value, src, dst) elif src in WEIGHT_TO_GRAM and dst in WEIGHT_TO_GRAM: result = convert_weight(args.value, src, dst) else: result = convert_temperature(args.value, src, dst) print(f"{args.value} {src} = {result} {dst}") if __name__ == "__main__": main() ``` 对应的 `test_converter.py`： ```python from converter import convert_temperature, convert_length, convert_weight def test_temperature(): assert convert_temperature(100, "C", "F") == 212.0 assert convert_temperature(0, "C", "K") == 273.15 assert convert_temperature(32, "F", "C") == 0.0 def test_length(): assert convert_length(1, "km", "m") == 1000.0 assert convert_length(1, "mile", "km") == 1.6093 def test_weight(): assert convert_weight(1, "kg", "g") == 1000.0 assert convert_weight(1, "lb", "kg") == 0.4536 ``` ### 7.4 运行与测试 在终端直接调用工具： ```bash python converter.py --from C --to F 100 # 100 C = 212.0 F python converter.py --from km --to mile 10 # 10 km = 6.2137 mile python converter.py --from lb --to kg 150 # 150 lb = 68.0388 kg ``` 跑测试（Claude 在生成过程中会自己执行这一步并把结果给你）： ```bash python -m pytest test_converter.py -v ``` 预期全部通过： ``` test_converter.py::test_temperature PASSED test_converter.py::test_length PASSED test_converter.py::test_weight PASSED ===== 3 passed in 0.02s ===== ``` ### 7.5 常见问题与解决 - **`pytest` 命令找不到**：本教程用的是 `python -m pytest`，前提是装了 pytest。Claude 会主动 `pip install pytest`；若你没装且离线，让它改用标准库的 `unittest` 重写测试。 - **换算结果与你心算不符**：八成是温度被当成线性换算了。这正是 `CLAUDE.md` 里特意写"温度换算与线性换算区分处理"的原因——好规矩能省掉返工。 - **想加新单位（如"光年"）**：直接对 Claude 说"在长度里加 light-year，并在测试里覆盖一组用例"，它会改库、加测试、重跑一遍。 ## 整体工作流 把从安装到交付的链路画清楚： ```text flowchart TD A[检查 Node.js ≥ 18] --> B[npm 全局安装 Claude Code] B --> C[claude 首次启动] C --> D{选择认证方式} D -->|Pro/Max 订阅| E[浏览器 OAuth 登录] D -->|API Key| F[设置 ANTHROPIC_API_KEY] E --> G[写 settings.json 权限与模型] F --> G G --> H[cd 进入项目 + claude] H --> I[/init 生成 CLAUDE.md 并润色] I --> J[自然语言下达任务] J --> K[Claude 读写文件/跑命令] K --> L{你确认改动} L -->|确认| M[跑测试通过] L -->|拒绝/修改| J M --> N[交付可运行工具] ``` ## 常见坑与排错清单 1. **每次都要点同意很烦**：把高频安全命令加进 `settings.json` 的 `allow`，或临时 `Shift+Tab` 切 `acceptEdits`，但永远别为了省事直接上 `bypassPermissions`。 2. **上下文越聊越贵**：换任务前 `/clear`；长会话用 `/compact`；随时 `/cost` 看消耗。 3. **Claude 忘了项目规矩**：确认规矩写进了项目根目录的 `CLAUDE.md`，而不是只口头说过一次。 4. **改动乱、不好回滚**：动手前先 `git init && git add -A && git commit -m init`，配合 `/review` 让 Claude 自查，出问题就 `git checkout` 回退。 5. **网络不稳定**：在 `settings.json` 的 `env` 里配 `HTTP_PROXY`/`HTTPS_PROXY`，比每次 export 省心。 6. **Windows 路径/换行问题**：直接用 WSL2，能避开 90% 的环境坑。 ## 训练营适用性评估 - **适合类型**：AI 编程零基础训练营、企业新员工 onboarding、高校"AI 辅助开发"导论课。本教程门槛低、产出可见，作为开营第一课非常合适。 - **预计教学时长**：讲授 + 跟做约 **2.5–3 小时**（安装认证 45 分钟，配置记忆 45 分钟，实战项目 60–90 分钟）。 - **可拓展方向**：在换算器基础上，后续课程可自然衔接到 Skill（把换算逻辑封装成可复用技能）、MCP（接入外部汇率 API 做货币换算）、自动化（用 `-p` 无头模式批量跑换算任务），形成由浅入深的课程梯度。 - **考核建议**：以"能独立装通 + 跑通测试 + 写出有效 CLAUDE.md"三项作为结业标准，换算器代码本身不评分，重在流程跑通。 ## 延伸阅读 - [Claude Code 官方文档总览](https://docs.anthropic.com/en/docs/claude-code/overview)：权限模式、子代理、内存层级等官方权威说明。 - [npm 包主页 @anthropic-ai/claude-code](https://www.npmjs.com/package/@anthropic-ai/claude-code)：最新版本号与安装参数。 - 进阶时回到本系列后续轮次：Skill 开发、MCP 服务器、Agent 自动化、上下文管理与性能优化。 ## 参考来源 1. [Claude Code 官方文档 Overview](https://docs.anthropic.com/en/docs/claude-code/overview) — Anthropic 官方对安装、认证、配置、工作流的权威说明。 2. [@anthropic-ai/claude-code npm 包](https://www.npmjs.com/package/@anthropic-ai/claude-code) — 全局安装命令与版本信息来源。 3. [2026 完整版 Claude Code 入门教程（CSDN）](https://blog.csdn.net/2611_95853909/article/details/162279647) — 中文社区从零安装到核心命令的实战教程。 4. [Claude Code CLI 配置 2026：5 分钟快速上手](https://blakecrosley.com/zh-Hans/blog/claude-code-quickstart) — 面向工程师的快速上手与 settings 配置实践。 5. [Claude Code 2026 完整使用指南（SoloSoft）](https://www.solosoft.dev/zh-cn/post/claude-code-complete-guide-2026/) — 覆盖权限模式、记忆系统与多代理架构的深度解析。 > [!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 等场景全覆盖。