知识点思维导图
29 个知识节点
Claude Code（02） - 安装与第一次对话
读完后，你应能完成以下任务：
- 绘制“Claude Code（02） - 安装与第一次对话 / 安装前你需要什么”的关键对象与数据流，解释“首次练习不要在 home 目录或包含大量无关文件的父目录启动。”，并用源码位置、日志或 Trace 标注证据。
- 为“Claude Code（02） - 安装与第一次对话 / 第一次启动与登录”设计正常与异常输入，验证“Claude 账号登录（推荐新手）：浏览器弹出授权页，点同意即可。 -> API Key：如果你有 Anthropic API Key，可以配成环境变量 ANTHROPIC_API_KEY。”，输出首个偏差位置与回归测试结果。
- 实现“Claude Code（02） - 安装与第一次对话 / 首次对话的执行模型”的最小代码或配置，检验“第一次提问不是把整个仓库一次性上传给模型。”，输出命令、结果与 Diff，并说明不适用边界。
本章目标：完成安装、登录认证和只读仓库探索，并能根据版本、认证、目录权限与网络四类信号定位首次启动失败。
一、安装前你需要什么
- 一个终端（macOS 的 Terminal/iTerm、Windows 的 PowerShell/WSL、Linux 的任意 shell 都行）。
- 能访问 Claude 服务的网络，以及可用的 Claude 账号或 Anthropic Console 账号。
- 一个具体的 Git 仓库。首次练习不要在 home 目录或包含大量无关文件的父目录启动。
Claude Code 当前推荐原生安装器； 旧 npm 安装方式已经被官方标记为 deprecated， 因此不应再把 Node.js 作为普通用户的安装前提。
二、安装
macOS / Linux 推荐使用官方安装器：
curl -fsSL https://claude.ai/install.sh | bash
macOS 也可以使用 Homebrew：
brew install --cask claude-code
Windows PowerShell 使用：
irm https://claude.ai/install.ps1 | iex
装完验证一下：
claude --version
能打印出版本号，就装好了。
如果机器里还残留 npm 版本，
先确认 which claude 或 Get-Command claude 实际命中了哪个可执行文件，
避免旧版本遮蔽原生安装版本。
不要用 sudo claude：它会改变配置目录与文件权限，
反而让普通用户后续无法读取会话。
三、第一次启动与登录
进入任意一个项目目录（重点：Claude Code 是「在某个项目里」工作的），
然后直接敲 claude：
cd ~/code/my-project # 换成你自己的项目
claude
第一次启动会引导你登录认证。两种常见方式：
- Claude 账号登录（推荐新手）：浏览器弹出授权页，点同意即可。
- API Key：如果你有 Anthropic API Key，可以配成环境变量
ANTHROPIC_API_KEY。
认证成功后，你会进入交互式对话界面。 认证只解决“你是谁”； Claude Code 能看到什么、能执行什么仍由当前工作目录、权限模式和每次工具授权共同决定。
3.1 首次对话的执行模型
第一次提问不是把整个仓库一次性上传给模型。
Claude Code 会先接收当前目录与规则上下文，
再按任务选择列目录、搜索符号、读取文件或执行命令；
工具结果回到会话后，模型才形成下一步判断。
因此回答是否可信，
要看它引用了哪些实际文件、命令有没有成功，
以及结论能否被你用 git diff、测试或源码再次验证。
这也解释了为什么启动目录很重要：目录过大造成检索噪声，目录过小又会漏掉工作区配置。 一个稳妥边界是仓库根目录； 若是 monorepo，再明确告诉它本次只读哪个 package。
四、跑通第一次对话
别急着让它改代码。 第一次，先让它「读懂」你的项目——这是最安全、最能建立信任的开场。 试试这句：
给我这个仓库的概览
它会做几件事（你能在屏幕上看到每一步）：
- 列目录、读关键文件（README、package.json 等）；
- 总结出：这是个什么项目、用了什么技术栈、目录怎么组织。
再追问一句，体会它「带着上下文回答」的能力：
这个项目是怎么启动的？入口在哪？
它会基于刚才读到的内容，直接告诉你启动命令和入口文件——而不是泛泛地讲「一般来说……」。
✅ 跑到这一步，你就完成了第一次对话。恭喜，你已经会用 Claude Code 的「只读模式」了。
五、几个一开始就该知道的操作
- 退出：输入
/exit或按Ctrl+C两次。 - 看能用哪些斜杠命令：输入
/，会列出所有可用命令（第 10 章细讲）。 - 多行输入：想换行而不发送，用
\结尾或按对应快捷键（界面里有提示）。 - 让它停下：它正在干你不想要的事？按
Esc打断。 - 继续上次对话：下次进项目想接着聊，用
claude --continue（接最近一次）或claude --resume（挑一个历史会话）。
六、失败定位：先判断卡在哪一层
| 现象 | 优先检查 | 判断依据 | 处理方式 |
|---|---|---|---|
claude: command not found |
安装与 PATH | which claude / Get-Command claude 无结果 |
重新运行原生安装器并重启终端 |
| 能启动但无法登录 | 认证与网络 | 浏览器授权是否完成、终端是否显示认证错误 | 重新登录；公司网络下核对代理与域名策略 |
| 回答像通用教程 | 目录与检索证据 | 回答没有具体文件路径或符号名 | 回到仓库根目录，要求先列出证据再回答 |
| 工具被拒绝 | 权限边界 | 界面明确显示 denied/cancelled | 只批准与当前任务匹配的最小操作，不要扩大到整机 |
| 修改后无法确认正确 | 验证链缺失 | 没有 diff、测试或构建结果 | 先查看 git diff，再运行最小相关测试 |
下面四类习惯错误会让上述问题反复出现：
错误 1：在家目录或一个超大目录里启动它
Claude Code 会以当前目录为「项目根」。
在 ~/ 或硬盘根目录启动，它面对成千上万个文件会很懵。
→ **永远在具体项目目录里启动。
**
错误 2：第一次就让它改核心代码 你还没建立对它的判断，它也还没摸清你的项目。 → 先用只读问题热身（概览、查找、解释），再逐步放开。
错误 3：装好后用 sudo claude
没必要，还可能引发权限和配置错乱。正常用户身份运行即可。
错误 4：以为它能记住跨项目的一切 每个项目的对话上下文是相对独立的。换项目 = 换一个工作现场。
七、最佳实践
- 确认安装来源：优先使用原生安装器，升级后用
claude --version和命令路径确认没有旧 npm 版本遮蔽。 - 项目里先跑
git init（如果还没有）：后面它改代码时，你能用git diff随时看改了啥，安全感拉满。 - 第一次对话只读不写：概览 → 查找 → 解释，三连热身。
- 认证信息别外泄：API Key 放环境变量，别写进会提交的文件里。
验收清单
- 安装：使用官方原生安装器或 Homebrew / WinGet，
claude --version验证。 - 启动：进具体项目目录，敲
claude，首次会引导登录。 - 证据：回答至少包含真实文件路径、入口或配置，且你能在仓库中复核。
- 安全：首次只读，不批准与问题无关的写文件、Shell 或网络操作。
- 验证：后续发生改动时，以
git diff和真实测试为准，而不是只看模型自述。
下一章，我们学怎么把话说清楚，让它准确听懂你要干嘛。
👉 04-基础交互.md
八、动手实践：Demo 02 · 一个用来练手的迷你项目
这是一个故意做得很小的示例项目（一个命令行待办清单）。 它的用途是：让你装好 Claude Code 后， 有个真实但不复杂的项目可以练习「第一次对话」。
8.1 怎么用
- 新建一个只含
todo.js与todos.json的练习目录，并在该目录启动claude。 - 用这些只读问题热身（不会改任何代码）：
给我这个仓库的概览 这个项目是怎么运行的？入口在哪？ 解释 @todo.js 里 addTodo 函数的逻辑 - 感受它「读懂项目后带着上下文回答」的能力。
8.2 项目本身怎么跑（可选）
node todo.js add "学习 Claude Code"
node todo.js list
数据存在同目录的 todos.json（首次运行自动创建）。
九、总结
- 安装前你需要什么：首次练习不要在 home 目录或包含大量无关文件的父目录启动。
- 跑通第一次对话：列目录、读关键文件（README、package.json 等）； -> 总结出：这是个什么项目、用了什么技术栈、目录怎么组织。
- 几个一开始就该知道的操作：退出：输入 /exit 或按 Ctrl+C 两次。
- 失败定位：先判断卡在哪一层：| 能启动但无法登录 | 认证与网络 | 浏览器授权是否完成、终端是否显示认证错误 | 重新登录；
- 首次对话的执行模型：第一次提问不是把整个仓库一次性上传给模型。
学完自测
选择所有正确答案；提交后逐项核对判断依据。