# WSL2 上装好 Claude Code 并跑通第一个项目（2026 全流程实战） ## 概述 本教程面向 Windows 10/11 用户，带你从零开始：启用 WSL2、安装 Ubuntu、配置 Node.js 环境、安装并认证 Claude Code，最终跑通一个真实的小型项目。完成后你将掌握 Claude Code 的完整安装链路、三种认证方式的选择、以及"用自然语言驱动 AI 生成可运行代码"的第一次实战体验。适合零基础开发者和首次接触命令行 AI 编程工具的学习者。 ## 前置条件 - Windows 10（21H2 / Build 19044+）或 Windows 11（22H2+） - 8 GB 以上内存（建议 16 GB） - 至少 5 GB 可用磁盘空间 - 以管理员身份运行 PowerShell 的权限 - 一个 Claude 账号（Pro/Max 订阅、Console API 账单、或企业平台任一即可） - 建议使用**英文 Windows 用户名**，避免后续中文路径踩坑 --- ## 一、先做选择：原生安装还是 WSL2？ 2026 年 Anthropic 已正式发布 Windows 原生版，所以现在你有两条主路线。对于做正式项目、会用 Node/Python/Docker 的开发者，社区与官方都更推荐 **WSL2**——它与 macOS/Linux 体验一致，社区教程几乎全部适用，且沙箱隔离更安全。 ### 30 秒决策树 ``` 你是 Windows 用户吗？ ├── 是 │ ├── 公司/IT 禁止装 WSL2？ → 走「原生安装器」（路径 A，2 分钟） │ ├── 会做 Node/Python/Docker 项目？ → 走「WSL2」（路径 B，推荐） │ ├── 内存 < 8 GB？ → 走「原生安装器」或「Git Bash」 │ └── 会用 VS Code/Cursor？ → 走「WSL2 + Remote-WSL」 └── macOS/Linux → 直接看第四节 ``` 下面先讲推荐路径 **WSL2**，再补原生安装器作为对照。 --- ## 二、路径 B：WSL2 完整安装（推荐，约 15 分钟） ### 第 1 步：启用 WSL2 并安装 Ubuntu 以**管理员身份**打开 PowerShell，执行： ```powershell wsl --install ``` 这条命令会自动启用「适用于 Linux 的 Windows 子系统」和「虚拟机平台」两个功能，并安装默认的 Ubuntu 发行版（建议选择 22.04 LTS，稳定且社区支持最完整）。安装完成后**重启电脑**。 重启后从开始菜单启动 Ubuntu，首次启动需要等待初始化，随后按提示创建一个 Linux 用户名和密码（与 Windows 账户无关，但请记住密码，后续 `sudo` 会用到）。 确认使用的是 WSL2 而非 WSL1： ```powershell wsl --set-default-version 2 wsl -l -v # 查看 VERSION 列应为 2 ``` ### 第 2 步：在 Ubuntu 内更新系统并安装 Node.js 进入 Ubuntu 终端后，先更新软件包： ```bash sudo apt update && sudo apt upgrade -y ``` 接下来用 **nvm（Node Version Manager）** 管理 Node.js，这是社区公认的最佳实践，能避免直接用 `sudo npm install -g` 带来的权限灾难： ```bash # 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash # 让 nvm 在当前 shell 生效 source ~/.bashrc # 安装 Node.js LTS 版本 nvm install --lts nvm use --lts # 验证 node -v # 应显示 v20.x 或更高 npm -v ``` ### 第 3 步：安装 Claude Code 官方现在提供统一安装脚本，会自动检测环境并装好 CLI： ```bash curl -fsSL https://claude.ai/install.sh | bash ``` 如果你更习惯 npm 方式（效果等价）： ```bash npm install -g @anthropic-ai/claude-code ``` > ⚠️ **切勿用 `sudo` 安装 npm 包**。遇到 `EACCES` 权限错误时，正确做法是把 npm 全局目录指到用户家目录，而不是提权： > ```bash > mkdir ~/.npm-global > npm config set prefix '~/.npm-global' > echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc > source ~/.bashrc > ``` ### 第 4 步：验证与体检 ```bash claude --version # 显示版本号即安装成功 claude doctor # 检查环境配置，给出诊断建议 ``` ### 第 5 步：完成首次认证 首次运行 `claude`，按提示选择认证方式： | 方式 | 适用人群 | 说明 | |------|---------|------| | **Anthropic Console** | 用 API 的开发者 | 需在 console.anthropic.com 有活跃账单，按 token 计费 | | **Claude Pro / Max** | Claude.ai 订阅用户 | Pro 约 $17/月，订阅即同时可用网页版和 Claude Code | | **企业平台** | 企业/合规场景 | 通过 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 访问 | 选择后会自动生成一个 URL，复制到 Windows 浏览器完成 OAuth 登录，成功后自动回到 WSL 终端。如果登录卡住，多半是 DNS/OAuth 拦截问题，参考第五节踩坑第 8 条。 --- ## 三、路径 A：原生安装器（快速体验，2 分钟） 如果你只想快速试用、不装 WSL，可走 Anthropic 官方原生安装器。以管理员身份打开 PowerShell： ```powershell irm https://claude.ai/install.ps1 | iex ``` 安装最新预览版： ```powershell & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest ``` 安装后**新开一个 PowerShell 窗口**，运行： ```powershell claude --version claude doctor ``` 若提示 `claude is not recognized`，说明 PATH 未生效，找到 `claude.exe` 路径（通常在 `C:\Users\<你>\AppData\Roaming\Anthropic\Claude\`）并加入系统环境变量。 > 原生版限制：无 Linux 沙箱、Bash 脚本需手动翻译成 PowerShell、依赖 Linux 工具的 MCP server 可能跑不动。做正式项目仍建议 WSL2。 此外还有 **WinGet**（`winget install Anthropic.ClaudeCode`，需手动 `winget upgrade` 更新）和 **Git Bash**（最轻量、功能受限）两种方式，作为补充。 --- ## 四、第一个项目实战：让 AI 生成一个可运行的 CLI 工具 环境装好后，我们来跑通第一个真实项目：用 Claude Code 从零生成一个 Node.js 命令行小工具——**文本统计器**（统计文件的字符数、单词数、行数）。 ### 步骤 1：创建项目目录 在 WSL Ubuntu 内（**不要**放在 `/mnt/c/` 下，性能会差 3–5 倍）： ```bash mkdir -p ~/projects/wordstat cd ~/projects/wordstat npm init -y ``` ### 步骤 2：启动 Claude Code ```bash claude ``` 进入交互界面后，先让它认识这个空项目。 ### 步骤 3：写第一句"项目记忆" CLAUDE.md 在 Claude Code 会话里直接输入： ``` 帮我创建一个 CLAUDE.md 文件，内容说明：这是一个用 Node.js 编写的文本统计 CLI 工具 wordstat，主要功能是统计给定文件的字符数、单词数、行数；技术栈为纯 Node.js（CommonJS），不使用第三方依赖。 ``` Claude Code 会自动生成 `CLAUDE.md`。这个文件相当于"项目说明书 + 团队约定"，未来每次进入项目都会自动加载，是 Claude Code 的核心机制之一。 ### 步骤 4：用自然语言生成核心代码 继续输入： ``` 请实现 wordstat 的主程序 index.js： 1. 接收一个文件路径作为命令行参数； 2. 读取文件内容（UTF-8）； 3. 统计并输出：字符数（不含换行）、单词数（按空白分隔）、行数； 4. 用 try/catch 处理文件不存在等错误，打印友好提示后退出码为 1。 ``` Claude Code 会读取 `package.json`、`CLAUDE.md`，然后生成 `index.js` 并展示变更预览，确认后写入文件。 ### 步骤 5：让它配好运行入口并实测 ``` 把 package.json 的 main 指向 index.js，并加一个 start 脚本 "start": "node index.js"。 然后新建一个测试样本 sample.txt，内容随便写几行中英文混合文本。 ``` 接着让它自测： ``` 用 wordstat 统计 sample.txt，告诉我输出是什么。 ``` Claude Code 会执行 `node index.js sample.txt` 并把结果贴回来，例如： ``` 字符数: 86 单词数: 14 行数: 5 ``` ### 步骤 6：让它补单元测试 ``` 为 index.js 写一个不依赖第三方库的测试 test.js，覆盖正常文件、空文件、不存在文件三种情况，并运行它。 ``` Claude Code 会创建 `test.js` 并运行，若有失败会**自动定位并修复**，直到全部通过。这正是 Claude Code 区别于传统补全工具的关键：它能理解整个项目、自主运行命令、根据反馈迭代。 ### 预期产出 一个结构清晰的小项目： ``` wordstat/ ├── package.json ├── CLAUDE.md ├── index.js ├── test.js └── sample.txt ``` 从空目录到可运行 + 有测试的 CLI 工具，全程只用自然语言驱动——这就是"跑通第一个项目"的完整闭环。 --- ## 五、整个工作流程 ```mermaid flowchart TD A[管理员 PowerShell] --> B{选择安装路线} B -->|正式项目/开发者| C[wsl --install
启用 WSL2 + Ubuntu] B -->|快速体验| Z[irm install.ps1
原生安装器] C --> D[重启 → 启动 Ubuntu] D --> E[apt update 更新系统] E --> F[装 nvm + Node.js LTS] F --> G[curl install.sh
或 npm i -g claude-code] G --> H[claude doctor 体检] H --> I[首次认证
Console / Pro / 企业] I --> J[cd ~/projects/xxx] J --> K[claude 启动会话] K --> L[生成 CLAUDE.md 项目记忆] L --> M[自然语言生成代码] M --> N[自动运行+测试+修复] N --> O[✅ 第一个项目跑通] style C fill:#e1f5ff style I fill:#fff4e1 style M fill:#e8f5e9 style O fill:#c8e6c9 ``` --- ## 六、Windows 用户高频踩坑速解 **1. `claude is not recognized`（PATH 问题）**　原生版常见，找到 `claude.exe` 实际路径并加入系统 PATH 环境变量。 **2. `npm install -g` 报 EACCES**　改 npm prefix 到 `~/.npm-global`（见第二节第 3 步），永远不要用 `sudo`。 **3. WSL 启动慢、吃内存**　在 Windows 家目录建 `C:\Users\<你>\.wslconfig` 限制资源： ``` [wsl2] memory=6GB processors=4 swap=8GB localhostForwarding=true ``` 改完执行 `wsl --shutdown` 再重启 Ubuntu。 **4. 中文路径乱码**　把项目搬出中文路径到 `~/projects/`，或设 `export LANG=zh_CN.UTF-8`。最治本：Windows 用户名用英文。 **5. OneDrive 同步冲突**　别把 git 项目放 OneDrive 目录，Claude Code 的文件监听会和 OneDrive 实时同步打架，导致锁文件或版本错乱。 **6. `/mnt/c/` 下项目慢 3–5 倍**　WSL2 跨 NTFS↔ext4 有开销，正式项目一律放 WSL 内部 `~/projects/`。 **7. Docker Desktop 抢资源**　确认 Docker Desktop 用 WSL2 backend，并在 Resources→WSL Integration 勾选你的 Ubuntu 发行版。 **8. OAuth 登录卡住**　多为 DNS 解析 OAuth 域名失败，换 DNS（如 `1.1.1.1`）或关闭可能拦截的代理/安全软件后重试。 **9. VS Code 连不上 WSL**　在主机装 VS Code + 「Remote - WSL」扩展，然后在 WSL 内执行 `code .`。 **10. WinGet 不自动更新**　WinGet 装的版本要手动 `winget upgrade Anthropic.ClaudeCode`，建议定期执行。 --- ## 延伸阅读 - Claude Code 官方文档（setup / advanced / IAM）：`code.claude.com/docs/en` - Microsoft 官方「Set up Node.js on WSL 2」指南：`learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl` - nvm 官方仓库及最新版本：`github.com/nvm-sh/nvm` - Anthropic 官方 Windows 安装脚本与原生支持说明 --- ## 训练营适用性评估 | 维度 | 评估 | |------|------| | 适合的训练营类型 | AI 编程入门营、前端/全栈新手营、企业内训"AI 提效"第一课 | | 学员基础要求 | 会基本命令行操作即可，零 Linux 经验也能跟做（但有 Linux 基础更顺） | | 预计教学时长 | 2–3 小时（含环境搭建 1 小时 + 首项目实战 1.5 小时 + 答疑） | | 实操比例 | 约 70%，全程命令驱动 + 真实项目产出 | | 适配人数 | 小班（≤20 人）最佳，便于逐台排查 WSL 环境；大班可提供预装镜像 | | 常见教学风险点 | WSL2 启用需重启、公司网络 OAuth 拦截、机器内存不足——建议提前发"环境预检清单" | --- ## 参考来源 1. [Windows 安装 Claude Code 完整指南：4 种方法详解（2026 年 1 月）](https://www.aifreeapi.com/zh/posts/claude-code-windows-install) — WSL/原生/WinGet/Git Bash 四种安装方式横评、认证方式、网络配置与 FAQ 2. [Claude Code Windows 安裝完整指南 2026：原生 vs WSL2 + 15 個踩坑全解](https://masonailab.com/tools/claude-code-installation-windows-wsl2-2026/) — 决策树、WSL2 资源调优、中文路径与 OneDrive 等真实踩坑解决方案 3. [How to Install Claude Code CLI on WSL2 Ubuntu](https://linuxbeast.com/blog/how-to-install-claude-code-cli-on-wsl2-ubuntu/) — WSL2 下用 nvm+Node.js 安装 Claude Code、认证与排错的英文实操 4. [Set up Node.js on WSL 2 — Microsoft Learn](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl) — 微软官方的 WSL2 Node.js 开发环境搭建指南 5. [Advanced setup — Claude Code Docs](https://code.claude.com/docs/en/setup) — Anthropic 官方安装与高级配置文档（npm 全局目录、更新机制等） > [!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 等场景全覆盖。