> 一篇给"零基础"读者的全程实操指南：从认清 2026 年的安装方式、完成登录认证，到用 `/init` 建立项目记忆、让 Claude 写出第一段可运行代码并提交到 Git。读完后，你将拥有一个完全由 Claude Code 协助搭建、可立即运行的命令行项目，并掌握日后排查"装不上、登不进、改不动"的标准动作。适用人群：从未用过命令行 AI 编程工具、想第一次就把环境搭对的学生与转岗开发者。 ## 一、前置条件：动手前先准备这四样 在敲第一条命令之前，确认你已经备齐下列条件，可以避开 90% 的"首跑失败"。 1. **一台受支持的操作系统**。根据官方《Advanced setup》页面，Claude Code 运行于：macOS 13.0+、Windows 10 1809+（或 Windows Server 2019+）、Ubuntu 20.04+、Debian 10+、Alpine 3.19+；硬件需要 4GB 以上内存、x64 或 ARM64 处理器。 2. **一个可用的账号**。三选一：Claude 订阅（Pro / Max / Team / Enterprise，最省心）、Claude Console（按量付费的 API 预充值额度）、或企业云（Amazon Bedrock / Google Vertex AI / Microsoft Foundry）。 3. **稳定的网络与受支持地区**。Claude Code 需要联网调用模型，且账号注册地区需在 Anthropic 支持的国家/地区列表内；如果你的网络无法直连，需要先解决代理或网关问题。 4. **一个"项目目录"**。哪怕只是一个空文件夹——Claude Code 是面向真实工程设计的，它需要在某个目录下工作，而不是凭空生成。 > 小提示：2026 年最大的变化是**官方原生安装器（Native Installer）已成为推荐方式**——它不再依赖 Node.js 与 npm，真正做到"零依赖、一条命令"。下文会以原生安装器为主线，npm 仅作兼容方案提及。 ## 二、安装：选对方法，三平台通用 Claude Code 现在提供六条安装通道。对零基础读者，推荐按"操作系统"对号入座，优先选原生安装器。 ### 2.1 macOS / Linux / WSL（推荐：原生安装器） 打开终端，执行一行命令即可： ```bash curl -fsSL https://claude.ai/install.sh | bash ``` 脚本会自动判断你的系统架构（x64 或 ARM64）、下载对应二进制、配置到本地路径，并启用**后台自动更新**——以后你不用再手动升级，新版本会在后台静默安装。 ### 2.2 Windows（原生安装器） Windows 用户需要先分清自己在用哪种终端，命令不同： PowerShell（提示符形如 `PS C:\>`）： ```powershell irm https://claude.ai/install.ps1 | iex ``` CMD（提示符形如 `C:\>`，无 `PS`）： ```batch curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd ``` 如果你执行后报错 `The token '&&' is not a valid statement separator`，说明你在 PowerShell 里跑了 CMD 命令；反之报 `'irm' is not recognized` 则是在 CMD 里跑了 PowerShell 命令。**看一眼提示符有没有 `PS` 即可分辨。** 额外建议：在原生 Windows 上安装 [Git for Windows](https://git-scm.com/downloads/win)，这样 Claude Code 才能用 Bash 工具执行命令；没装的话它会退而使用 PowerShell。如果你用的是 WSL 2，则无需 Git for Windows。 ### 2.3 包管理器（适合已有工具链的用户） - macOS Homebrew（稳定版，约滞后一周）： ```bash brew install --cask claude-code ``` 想要最新版则用 `claude-code@latest`。注意 Homebrew 安装**不会自动更新**，需要定期手动 `brew upgrade`。 - Windows WinGet： ```powershell winget install Anthropic.ClaudeCode ``` 同样不自动更新，记得 `winget upgrade Anthropic.ClaudeCode`。 - Linux：在 Debian/Fedora/RHEL/Alpine 上也可用 `apt` / `dnf` / `apk` 安装。 ### 2.4 预期结果 安装完成后，运行下面这条命令验证： ```bash claude --version ``` 正常会打印出形如 `2.x.x` 的版本号。如果看到 `command not found`，通常是 PATH 未生效——关闭并重开一个终端窗口再试；若仍不行，参考第六节的排查清单。 ### 2.5 常见问题 | 现象 | 原因 | 解决 | | --- | --- | --- | | `command not found: claude` | PATH 未刷新 | 重开终端；或手动把安装目录加入 PATH | | 下载脚本卡住/超时 | 网络无法直连 Anthropic | 配置代理或 LLM 网关后再跑 | | 权限错误 `Permission denied` | 安装目录不可写 | 改用有写权限的用户目录安装 | | 搜索功能报错 | ripgrep 缺失 | 多数版本已内置；缺失时手动安装 ripgrep | ## 三、登录认证：第一次启动会引导你完成 Claude Code 必须登录账号才能使用。在任意目录直接输入： ```bash claude ``` 首次启动会弹出认证流程：浏览器打开一个授权页面，确认后回到终端，凭据会被安全存储在本地，之后无需重复登录。 如果你想切换账号或重新认证，进入会话后输入斜杠命令： ```text /login ``` **预期结果**：终端顶部出现 Claude Code 的提示符，显示当前版本、所用模型和工作目录，说明登录成功。 **常见问题**：浏览器没有自动弹出？手动复制终端里显示的链接到浏览器即可；登录后报"地区不支持"，则需确认账号地区或改用企业云通道。 ## 四、建立第一个项目并启动会话 环境就绪后，我们来搭建一个真实目录作为首个项目。这里以构建一个"命令行待办（Todo）小工具"为贯穿案例。 ### 4.1 创建项目目录 ```bash mkdir my-todo && cd my-todo ``` 进入目录后启动 Claude Code： ```bash claude ``` ### 4.2 用 /init 生成项目记忆（CLAUDE.md） 这是新手最该学的第一个斜杠命令。在会话里输入： ```text /init ``` `/init` 会扫描当前目录，自动生成一份 `CLAUDE.md`——这是 Claude Code 的"持久简报"，记录项目用的技术栈、目录结构、构建命令、代码规范等。它的价值在于：**以后每次开会话，Claude 都会先读这份文件，免得你每次都从头解释项目。** 对一个空目录，`/init` 会生成一份模板，你随后可以让 Claude 帮你补全。例如接着说： ```text 这是一个用 Python 实现的命令行待办工具，用 Click 做命令行参数。 请把 CLAUDE.md 补充完整，包含项目说明、依赖、运行方式和目录结构。 ``` **预期结果**：项目根目录出现 `CLAUDE.md`，内容包含项目摘要、技术栈、命令清单。Claude 会先展示它打算写入的内容，征求你同意后再落盘——这是它"改文件前必先确认"的安全机制。 ## 五、让 Claude 写出第一段可运行代码 现在进入正题：让 Claude 真正动手写代码。 ### 5.1 提出第一个需求 在会话里用自然语言描述： ```text 用 Click 实现一个 todo 命令行工具：支持 todo add <内容> 添加任务， todo list 列出任务，todo done <编号> 标记完成。 任务存在当前目录的 todos.json 里。 ``` Claude Code 会按"代理循环"自主推进：分析需求 → 决定要创建/修改哪些文件 → 写出代码 → 展示变更 → 请求批准。它通常会创建一个 `todo.py` 和 `requirements.txt`。 **预期结果**：Claude 弹出文件变更预览（diff），你可以： - 逐个查看并批准； - 或开启 **Accept all** 模式，本次会话内自动接受所有改动（适合信任度高的简单项目，正式工程建议保持逐条审批）。 ### 5.2 运行验证 批准后，你可以直接让 Claude 帮你跑起来： ```text 安装依赖并跑一次：先 todo add "读完 Claude Code 入门"，再 todo list 看看输出。 ``` Claude 会调用 Bash 工具执行 `pip install -r requirements.txt`、`python todo.py add "读完 Claude Code 入门"`、`python todo.py list`，并把真实输出回贴给你。你应当看到任务被正确添加并以带编号列表显示。 ### 5.3 常见问题 - **报错 `ModuleNotFoundError: No module named 'click'`**：依赖没装。让 Claude 执行安装，或确认用的 Python 解释器与安装依赖的是同一个。 - **改动不符合预期**：直接在会话里说"把存储格式从 JSON 改成 CSV"，Claude 会增量修改，无需推倒重来。 - **想撤销**：可以用 `/undo` 撤回最近的改动，或依赖下一步的 Git 回滚。 ## 六、用 Git 给项目"上保险" Claude Code 把 Git 操作变成了对话。先初始化仓库（如果还没有）： ```text 帮我 git init，然后把当前改动提交，commit message 要描述清楚这是首版 todo 工具。 ``` Claude 会执行 `git init`、`git add`、`git commit`，并把 commit message 草稿展示给你确认。你还可以继续对话式操作： ```text 新建分支 feature/export ``` ```text 显示最近 3 次提交 ``` ```text 如果 todo.json 里的任务太多，帮我加一个 todo export 命令导出成 markdown，并提交。 ``` **预期结果**：每次改动都有清晰的提交记录，配合 `CLAUDE.md`，整个项目的演进可追溯、可回滚。 ## 七、实战案例：端到端构建 Todo CLI（完整复盘） 下面把前几步串成一个可复现的完整流程。你在自己的机器上照做，能跑出同样的结果。 **目标**：一个 Python + Click 的命令行待办工具，数据存 JSON，支持增/列/完成/导出。 **步骤**： 1. 建目录并启动： ```bash mkdir my-todo && cd my-todo claude ``` 2. 初始化项目记忆： ```text /init （随后补充）这是 Python + Click 的 CLI 待办工具，数据存 todos.json。 ``` 3. 让 Claude 生成核心代码： ```text 实现 todo add/list/done 三个子命令，任务带自增编号、内容、完成状态。 ``` 4. 运行并自测： ```text 装 Click，依次执行：add "学 /init"、add "写第一段代码"、list、done 1、list。 把输出贴给我看。 ``` 5. 加一个增强功能并修一个"故意留的 bug"： ```text 加 todo export 导出 markdown；另外 list 时已完成任务不应该还能被 done，请检查并修复这个 bug。 ``` 6. 用 Git 落盘： ```text git init 并提交首版，message 说明功能范围。 ``` **最终产物**：项目目录包含 `todo.py`、`requirements.txt`、`todos.json`、`CLAUDE.md`，并有一个干净的 Git 历史。整个过程你几乎没手写代码——你的角色是"提需求 + 审批 + 验证"，Claude 负责实现与执行。 下面这张流程图概括了从安装到跑通的完整工作流： ```text flowchart TD A[准备: 系统/账号/网络/项目目录] --> B[安装: 原生安装器/包管理器] B --> C{claude --version 成功?} C -- 否 --> T[排查 PATH/网络/权限] T --> B C -- 是 --> D[登录: claude → /login] D --> E[cd 项目目录 → claude 启动会话] E --> F[/init 生成 CLAUDE.md 项目记忆] F --> G[自然语言提需求 → 审批变更] G --> H[让 Claude 跑代码自测] H --> I{符合预期?} I -- 否 --> G I -- 是 --> J[对话式 Git 提交] J --> K[首个项目跑通 ✅] ``` ## 八、延伸阅读 - **官方快速上手**：`code.claude.com/docs/en/quickstart`——七步法带你完成首次会话。 - **高级安装设置**：`code.claude.com/docs/en/setup`——系统要求、各平台细节、版本管理与卸载。 - **安装与登录排障**：`code.claude.com/docs/en/troubleshoot-install`——专治"command not found、PATH、权限、网络、认证"五类问题。 - **CLAUDE.md 与项目记忆**：研究 `/init` 背后的记忆层级，让 Claude 越用越懂你的项目。 - **下一步进阶**：熟悉斜杠命令后，可以探索 Skills（自定义技能）、Hooks（自动化钩子）和 MCP（外部工具协议），把单次"首跑"升级为可复用的工程化能力。 ## 九、训练营适用性评估 - **适用类型**：面向"AI 编程零基础"的入门训练营、企业新员工 onboarding 训练营、高校 AI 工具通识课的第一节课。 - **教学时长**：建议 **90–120 分钟**（含动手）。其中安装与登录约 30 分钟（受网络情况影响浮动最大），`/init` 与首段代码约 40 分钟，Git 收尾与答疑约 30 分钟。 - **分组建议**：每 2–3 人一组共用一台机器，一人提需求、一人审批、一人记录踩坑，能最快暴露新手常见误区。 - **评估标准**：以"项目能运行 + `CLAUDE.md` 完整 + Git 有至少两次提交"作为通关条件；额外加分项为"主动用对话修复一个 bug 并说明原因"。 - **进阶衔接**：本节完成后，可自然过渡到"斜杠命令体系""Skills 开发""MCP 工具接入"等主题，形成入门→进阶的完整训练闭环。 ## 参考来源 1. [Quickstart — Claude Code Docs](https://code.claude.com/docs/en/quickstart) — 官方七步快速上手，覆盖安装、登录、首问、首改、Git、修 Bug。 2. [Advanced setup — Claude Code Docs](https://code.claude.com/docs/en/setup) — 系统要求、原生安装器与各平台安装细节、版本管理。 3. [Troubleshoot installation and login — Claude Code Docs](https://code.claude.com/docs/en/troubleshoot-install) — 官方排障手册，覆盖 command not found / PATH / 权限 / 网络 / 认证。 4. [2026 年 Claude Code 安装完全指南：Mac、Windows 与 Linux 三平台教程 — 老张的博客](https://blog.laozhang.ai/zh/posts/how-to-install-claude-code) — 中文社区对六种安装方式与零依赖原生安装器的对照讲解。 5. [Initialize Your First Project — Developer Toolkit](https://developertoolkit.ai/en/claude-code/quick-start/first-project/) — 详解 `/init`、`CLAUDE.md` 记忆层级与项目初始化实践。 > [!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 等场景全覆盖。