1. 为什么要在 Windows 上认真折腾 Claude Code
1.1 这个工具到底解决什么问题
Claude Code 是 Anthropic 推出的命令行 AI 编程助手，它跟网页版聊天最大的区别在于：它能直接读写你本地的项目文件、执行终端命令、跑测试、改代码，相当于把一个懂你整个代码库的结对程序员塞进了终端里。你在项目根目录敲一句自然语言，它就能自己去找相关文件、理解上下文、动手改代码，改完还能帮你跑一遍构建验证。
但问题来了——这套东西原生是给 macOS 和 Linux 设计的。官方文档里那些brew install、curl | bash的安装方式，在 Windows 上要么跑不通，要么跑通了也各种别扭。我身边不少朋友第一次装的时候，卡在环境变量、路径分隔符、权限报错上折腾了大半天，最后放弃转去用网页版了。
这篇东西就是把我自己在 Windows 上从零落地 Claude Code 的全过程拆开讲清楚。包括装什么、怎么配、哪些坑必须提前避开、装完之后怎么调优让它跑得顺。适合两类人看：一是完全没接触过命令行 AI 工具、想从零上手的 Windows 用户；二是已经装过但被各种报错劝退、想搞清楚底层原理再重新搞一遍的人。
1.2 Windows 上跑 Claude Code 的核心矛盾
先说清楚为什么 Windows 上会这么麻烦。Claude Code 本质上是一个 Node.js 写的 CLI 工具，它依赖几个东西：Node 运行时、npm 包管理器、一个能跑 shell 命令的环境、以及对文件系统的读写权限。
在 macOS/Linux 上，这些东西天然就是一套的，shell 是 bash/zsh，路径用正斜杠，权限模型清晰。但 Windows 有两套东西在打架：一套是传统的 CMD/PowerShell + 反斜杠路径 + 盘符，另一套是 WSL（Windows Subsystem for Linux）提供的完整 Linux 环境。
Claude Code 内部执行命令时默认走的是 POSIX shell 那套逻辑，所以如果你直接在 PowerShell 里跑，经常会遇到命令找不到、路径解析错误、脚本执行策略被拦这些问题。这就是为什么很多人装完发现"能启动但一让它干活就报错"。
理解了这个矛盾，后面的方案选型就顺理成章了：要么给它一个真正的 Linux 环境（WSL2），要么在 Windows 原生环境下把兼容层配好。两条路我都走过，下面分别说。
2. 安装前的环境准备与方案选型
2.1 两条路线怎么选：WSL2 还是原生 Windows
这是整个落地过程里最重要的一个决策，选错了后面全是坑。我先把两条路线的对比摆出来，你对着自己的情况选。
| 对比维度 | WSL2 路线 | 原生 Windows 路线 |
|---|---|---|
| 环境兼容性 | 几乎完美，等同 Linux | 需要额外配置兼容层 |
| 文件性能 | 访问 Windows 盘符较慢 | 本地文件读写快 |
| 安装复杂度 | 中等，需装 WSL2 | 较低，装 Node 即可 |
| 权限问题 | 少，Linux 权限模型 | 较多，需处理执行策略 |
| 适合场景 | 重度使用、多项目 | 轻度使用、尝鲜 |
| 磁盘占用 | 较大（几个 GB） | 较小 |
我的建议很直接：如果你打算长期用、每天都要跑，直接上 WSL2，别犹豫。虽然初始配置多花半小时，但后面省下的排查时间远超这个成本。如果你只是想试试看、偶尔用一下，那原生 Windows 路线也能跑，但要做好心理准备。
提示：WSL2 需要 Windows 10 版本 2004 及以上，或者 Windows 11。老版本系统只能走原生路线。
2.2 基础依赖的安装顺序
不管走哪条路线，有几个基础依赖是绕不开的。我把顺序理一下，这个顺序不能乱，乱了会出依赖问题。
第一步是 Node.js。Claude Code 要求 Node 18 以上，我实测用 Node 20 LTS 最稳。去官网下 Windows 安装包，一路下一步就行。装完在终端敲node -v和npm -v验证，能出
