首页 › tutorials › 装好Claude Code并跑通首个项目

一篇给"零基础"读者的全程实操指南：从认清 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（推荐：原生安装器）

打开终端，执行一行命令即可：

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

脚本会自动判断你的系统架构（x64 或 ARM64）、下载对应二进制、配置到本地路径，并启用后台自动更新——以后你不用再手动升级，新版本会在后台静默安装。

2.2 Windows（原生安装器）

Windows 用户需要先分清自己在用哪种终端，命令不同：

PowerShell（提示符形如 PS C:\>）：

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

CMD（提示符形如 C:\>，无 PS）：

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，这样 Claude Code 才能用 Bash 工具执行命令；没装的话它会退而使用 PowerShell。如果你用的是 WSL 2，则无需 Git for Windows。

2.3 包管理器（适合已有工具链的用户）

2.4 预期结果

安装完成后，运行下面这条命令验证：

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 必须登录账号才能使用。在任意目录直接输入：

claude

首次启动会弹出认证流程：浏览器打开一个授权页面，确认后回到终端，凭据会被安全存储在本地，之后无需重复登录。

如果你想切换账号或重新认证，进入会话后输入斜杠命令：

/login

预期结果：终端顶部出现 Claude Code 的提示符，显示当前版本、所用模型和工作目录，说明登录成功。

常见问题：浏览器没有自动弹出？手动复制终端里显示的链接到浏览器即可；登录后报"地区不支持"，则需确认账号地区或改用企业云通道。

四、建立第一个项目并启动会话

环境就绪后，我们来搭建一个真实目录作为首个项目。这里以构建一个"命令行待办（Todo）小工具"为贯穿案例。

4.1 创建项目目录

mkdir my-todo && cd my-todo

进入目录后启动 Claude Code：

claude

4.2 用 /init 生成项目记忆（CLAUDE.md）

这是新手最该学的第一个斜杠命令。在会话里输入：

/init

/init 会扫描当前目录，自动生成一份 CLAUDE.md——这是 Claude Code 的"持久简报"，记录项目用的技术栈、目录结构、构建命令、代码规范等。它的价值在于：以后每次开会话，Claude 都会先读这份文件，免得你每次都从头解释项目。

对一个空目录，/init 会生成一份模板，你随后可以让 Claude 帮你补全。例如接着说：

这是一个用 Python 实现的命令行待办工具，用 Click 做命令行参数。
请把 CLAUDE.md 补充完整，包含项目说明、依赖、运行方式和目录结构。

预期结果：项目根目录出现 CLAUDE.md，内容包含项目摘要、技术栈、命令清单。Claude 会先展示它打算写入的内容，征求你同意后再落盘——这是它"改文件前必先确认"的安全机制。

五、让 Claude 写出第一段可运行代码

现在进入正题：让 Claude 真正动手写代码。

5.1 提出第一个需求

在会话里用自然语言描述：

用 Click 实现一个 todo 命令行工具：支持 todo add <内容> 添加任务，
todo list 列出任务，todo done <编号> 标记完成。
任务存在当前目录的 todos.json 里。

Claude Code 会按"代理循环"自主推进：分析需求 → 决定要创建/修改哪些文件 → 写出代码 → 展示变更 → 请求批准。它通常会创建一个 todo.py 和 requirements.txt。

预期结果：Claude 弹出文件变更预览（diff），你可以：

5.2 运行验证

批准后，你可以直接让 Claude 帮你跑起来：

安装依赖并跑一次：先 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 常见问题

六、用 Git 给项目"上保险"

Claude Code 把 Git 操作变成了对话。先初始化仓库（如果还没有）：

帮我 git init，然后把当前改动提交，commit message 要描述清楚这是首版 todo 工具。

Claude 会执行 git init、git add、git commit，并把 commit message 草稿展示给你确认。你还可以继续对话式操作：

新建分支 feature/export

显示最近 3 次提交

如果 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 负责实现与执行。

下面这张流程图概括了从安装到跑通的完整工作流：

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[首个项目跑通 ✅]

八、延伸阅读

九、训练营适用性评估

参考来源

  1. Quickstart — Claude Code Docs — 官方七步快速上手，覆盖安装、登录、首问、首改、Git、修 Bug。
  2. Advanced setup — Claude Code Docs — 系统要求、原生安装器与各平台安装细节、版本管理。
  3. Troubleshoot installation and login — Claude Code Docs — 官方排障手册，覆盖 command not found / PATH / 权限 / 网络 / 认证。
  4. 2026 年 Claude Code 安装完全指南：Mac、Windows 与 Linux 三平台教程 — 老张的博客 — 中文社区对六种安装方式与零依赖原生安装器的对照讲解。
  5. Initialize Your First Project — Developer Toolkit — 详解 /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 等场景全覆盖。

51学通信知识星球海报-扫码加入

📎 本分类最新文章