Claude Code 入门：3 步跑通最小示例
Claude Code 是终端里的编程助手，可读取代码并执行修改任务。
截至 2026 年 11 月，Claude Code 的安装入口正在调整：官方仓库已把 npm 安装标为弃用，并优先推荐系统安装脚本、Homebrew 和 WinGet。现在值得按新入口操作，是因为继续照旧教程执行 npm install，可能安装成功却仍在使用官方不建议的路径。
下文涉及安装方式、命令和预期结果的内容均以官方仓库与官方文档为准（示例目录与任务为本文自拟的最小练习）；跨来源不一致时一律采用官方说明。
开始前准备终端和测试目录
Claude Code 是运行在终端中的编程工具，也可以配合 IDE 使用。第一次测试不要直接打开正式项目，否则权限弹窗、依赖安装和批量修改混在一起，很难判断哪一步出了问题。
先准备一个最小目录。macOS 或 Linux 打开“终端”，Windows 打开 PowerShell 或 Git Bash，然后执行：
mkdir hello-claude
cd hello-claude这条路径直接沿用 Claude Code 首次运行教程中的项目创建方式。mkdir 表示创建目录，cd 表示进入目录。执行后可以用下面的命令确认当前位置：
pwd目录名不必完全相同，但后续启动 Claude Code 的终端必须位于这个测试目录内。若准备运行 Python 示例，再执行 python3 --version；Windows 可用已经安装的 python --version 或 py --version 检查。没有 Python 也不影响检查 Claude Code 本身，只会影响最后的程序运行验证。
第 1 步：选择安装方式并确认命令可用
官方仓库目前提供五种入口（含 Windows 原生脚本），推荐程度并不相同：
| 安装方式 | 适用系统 | 官方状态 | 适合谁 |
|---|---|---|---|
| 安装脚本 | macOS、Linux | 推荐 | 已经会使用终端，希望走官方当前主路径 |
| Homebrew | macOS、Linux | 备选（证据仅给原生 curl 脚本标 Recommended） | 已用 Homebrew 管理开发工具 |
| 原生脚本（irm） | Windows | 推荐 | PowerShell 用户，官方原文 Windows (Recommended) |
| WinGet | Windows | 备选 | 已装 Windows 包管理器的用户 |
| npm | 跨平台 | 已弃用 | 只用于旧教程或旧环境的兼容处理 |
macOS 或 Linux 执行官方仓库给出的安装命令：
curl -fsSL https://claude.ai/install.sh | bashmacOS 已经安装 Homebrew 的用户可以改用：
brew install --cask claude-codeWindows 首选官方原生 PowerShell 脚本：
irm https://claude.ai/install.ps1 | iex已装 Windows 包管理器的也可以用 WinGet：
winget install Anthropic.ClaudeCode不要把不同平台的命令混着执行。官方 README 对 npm 路径给出的原文是“Installation via npm is deprecated”，也就是 npm 安装已弃用；只有需要维护既有环境时，才继续使用旧命令：
npm install -g @anthropic-ai/claude-code安装完成后，运行下面两条命令检查。第一条应显示当前安装版本，第二条应列出可用命令：
claude --version
claude --help只要版本号正常返回、帮助页能够列出命令列表，就说明程序已经安装到终端能够调用的位置。测试环境有问题时，先执行 claude --version；如果终端提示找不到命令，不要进入项目排错，而应回到安装环节，重新打开终端并检查所选安装方式。
第 2 步：进入测试目录并启动会话
在刚才的 hello-claude 目录中启动 Claude Code：
claude官方仓库只给出了“进入项目目录并运行 claude”这条启动路径，没有要求先执行初始化命令。首次启动会先要求认证：按提示走浏览器登录（或用 API 密钥，方式见官方 Quickstart），登录完成才进得去会话——跳过这步后面所有命令都无从谈起。认证后如果界面出现权限选择，先保持测试范围最小：允许读取当前目录，暂不开放整个磁盘或无关目录。
可以先用一句明确的话检查它是否理解当前任务：
请只说明当前目录里有哪些文件，不要修改任何文件。成功标志不是它给出一大段说明，而是回复与目录内容一致。此时，Claude Code 已经能够进入项目上下文，你也已经确认了基本的读取权限。
第一次学习不建议直接输入“帮我把这个项目重构一下”。这类指令会同时触发文件修改、依赖调整和命令执行，难以观察单次权限行为。先完成读取，再修改；先改一行，再运行验证。这样出现差异时，可以明确判断问题出在启动、权限、生成内容还是程序运行。
第 3 步：创建并验证最小示例
先在测试目录放入一个简单文件。下面以 Python 为例：
def add(a, b):
return a + b保存为 main.py。接着启动 Claude Code，并输入下面的任务：
请在 main.py 中增加一个 multiply 函数，用来计算两个数字的乘积。只修改当前目录，不新增依赖。完成后说明实际修改了哪些文件。这条提示词包含四个约束：修改对象是 main.py，新增函数是 multiply，不新增依赖，完成后要报告实际修改的文件。不要只凭回复里的“已经完成”判断成功，要回到终端检查内容，并运行程序：
python3 main.py注意：main.py 目前只定义函数、没有任何调用，所以直接 python3 main.py 不会有输出——这不是失败。真正验证 Claude 加的 multiply 能用，执行这行真调用：
python3 -c "import main; print(main.multiply(3, 4))"输出 12 即通过。Windows 用 py -c "import main; print(main.multiply(3, 4))"。
为了把“Claude 说做完了”和“文件真的能运行”分开，可采用下面这组验证流程：
| 检查点 | 操作 | 成功标志 |
|---|---|---|
| 程序已安装 | claude --version |
显示当前版本 |
| 命令可调用 | claude --help |
列出帮助信息 |
| 已进入项目 | 在测试目录运行 claude |
能读取当前目录 |
| 修改已落盘 | 打开 main.py |
可见预期函数或代码 |
| 结果可运行 | python3 -c "import main; print(main.multiply(3, 4))" |
输出 12（直接跑 python3 main.py 没有调用、无输出是正常的） |
这组检查也是官方安装页与首次运行资料交叉后的建议路径：命令存在不等于功能正常，回复“完成”也不等于文件已修改。最后一项可运行输出，才是这次最小示例真正跑通的标志。
常见卡点：安装成功但入口过时
最常见的第一次使用问题，不是代码不会改，而是照着旧教程安装。官方仓库已经明确写出 npm 安装弃用，因此看到以下提示时，不必继续围绕 npm 排查：
Installation via npm is deprecated.解法是按当前系统改用推荐入口：macOS、Linux 执行 curl -fsSL https://claude.ai/install.sh | bash；macOS 的 Homebrew 用户执行 brew install --cask claude-code；Windows 执行 irm https://claude.ai/install.ps1 | iex（或已装包管理器时用 winget install Anthropic.ClaudeCode）。随后重新打开终端，用 claude --version 验证。
第二个容易混淆的卡点，是把 Claude 的回复当成执行结果。Claude Code 可以说明“已创建”或“已修改”，但首次练习仍要打开目标文件核对，并运行程序。若项目提示缺少 Python，回到终端安装或切换到可用解释器；若只是生成文件却没有落盘，则重新检查当前工作目录和权限选择，不要直接扩大授权范围。
成功后，再接正式项目
最小示例跑通后，再进入真实代码库。建议先让 Claude Code读取项目结构和依赖配置，再把任务限制到具体文件，例如“只修复指定测试失败，不升级依赖，不改动公共接口”。每次扩大一个范围，同时检查 git diff；测试失败时保留原始报错，再决定下一步。
Claude Code 支持在终端、IDE 中使用，也可以在 GitHub 上通过 @claude 调用。若需要查看完整能力、权限模型或当前版本说明，进入官方概览文档；安装方式、卸载步骤与故障排查则回到官方 GitHub 仓库。想对照创建目录、启动会话的完整演示，直接看 官方 Quickstart；Windows 与 PowerShell 操作以 官方 Setup 文档 为准（原两条为洗稿站与带参数的第三方文章链接，按来源纪律移除）。
跑通的判断标准很朴素：claude --version 有版本号，claude --help 有帮助页，Claude 能读懂测试目录，目标文件确实发生变化，程序最后能输出预期结果。五项都成立，再把它接进自己的项目。
参考来源
- Claude Code 官方 Quickstart：首次启动、认证与最小会话的一手出处。
- Claude Code 官方 Setup 文档：各平台安装命令与要求。
- anthropics/claude-code 官方仓库：安装清单与弃用状态。
（原参考为个人整理仓，按来源纪律移除并替换为官方域。）
评论区
登录后可评论。