信浮沉在 Windows 上装 Claude Code 这件事，我前前后后折腾了不止一次，每次都会被各种奇奇怪怪的报错卡住。最近又完整跑了一遍从零到一的流程，从 Node 环境准备、npm 全局安装，到首次启动登录、模型配置，再到真实跑一个小项目，中间踩了不少坑，也整理出了一套比较顺的路径。这篇文章就把整个过程记录下来，包括每一步的验证方法、报错原因和解决思路，尽量做到保姆级。内容适合想在 Windows 上使用 Claude Code 的开发者，不管你是刚摸命令行的新手，还是已经用过 Cursor、GitHub Copilot 这类工具的老手，照着这份记录走，基本能少走一半弯路。
1. 安装前的认知准备：Claude Code 到底是个什么工具
1.1 Claude Code 是什么，和网页版 Claude 有什么区别
Claude Code 是 Anthropic 推出的命令行 AI 编程代理工具，定位是“住在你终端里的 AI 程序员”。和网页版 Claude 不一样，它直接跑在本地命令行里，能够读取当前项目的文件、执行命令、修改代码、运行测试，甚至替你完成一系列多步骤的编程任务。网页版更多是问答和写作，而 Claude Code 强调的是“动手干活”。
很多刚接触的人会问：既然我可以用网页版把代码复制给 Claude，让它给我写，为什么还要装一个命令行工具？
简单说，两者的区别在于“工作方式”。网页版是你把上下文喂给它，它给你一段代码，你再手动粘贴、测试、修复，循环往复；而 Claude Code 是它自己去看你的代码仓库，自己动手改文件，自己跑命令，你只需要在旁边确认它每一步的意图。这种模式下，改一个 Bug、重构一个模块、补一批单测，效率会明显高出一截。
1.2 Windows 下使用 Claude Code 的主流方案有哪些
在 Windows 上跑 Claude Code，目前主流的方案有两类。
一是原生 Windows 方案。Claude Code 官方支持 Windows，通过 npm 包分发，直接在 Windows 的终端（PowerShell 或 CMD）里安装运行。优点是环境简单，不依赖虚拟机或子系统，文件和路径都是 Windows 原生的，适合大部分普通用户。
二是 WSL（Windows Subsystem for Linux）方案。WSL 是微软官方提供的 Linux 兼容层，在 Windows 里跑一个完整的 Linux 发行版。在 WSL 里安装 Claude Code，本质上是在 Linux 环境下运行，和很多 Linux 服务器上的行为一致。这个方案更适合长期做后端开发、把 Linux 当主战场的开发者，因为工具链、路径、权限模型和服务器更贴近。
现在官方对 Windows 原生的支持已经比较完善，不再是“只能用 WSL”的时代了。但很多老教程还停留在“Windows 用户请先装 WSL”的阶段，导致新手绕了不少路。我的建议是：先装原生版本，简单顺滑；如果后面确实需要和 Linux 工具链对接，再考虑 WSL。
1.3 两种方案的取舍逻辑
选原生还是 WSL，核心看三件事。
第一，你平常用什么终端。如果你已经习惯 PowerShell、CMD，而且主要接触 Windows 生态（比如 .NET、PowerShell 脚本、Windows 桌面应用），原生版更合适，它不需要你在两套系统之间切换。
第二，你的项目跑在什么环境。如果项目最终要部署到 Linux 服务器，而且本地开发也用 Docker、bash 脚本、Linux 工具链，那 WSL 的体验会更一致。你在 WSL 里装的 Claude Code 可以直接操作 Linux 文件系统，权限、符号链接、路径分隔符都不会出问题。
第三，你的电脑配置和习惯。WSL 会额外占用一些内存和磁盘空间，如果机器配置一般，原生版会更轻量。另外，如果你对 WSL 的存储位置、网络模型不熟悉，遇到问题排查成本更高。
我个人的选择是：日常写脚本、做前端小项目用原生 Windows；涉及到部署脚本、Docker 镜像构建这些 Linux 味道很重的任务时，切到 WSL 里跑。两个方案不冲突，可以共存，这篇教程会把两条路都讲清楚，你按自己的情况挑一条。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备：把前置依赖一次性装好
真正开始装 Claude Code 之前，有几个前置条件需要确认。这些步骤看起来简单，但恰恰是很多人卡住的起点。我见过不少朋友直接跳到 npm install，然后报一堆错，回头才发现 Node 版本太老或者压根没装 Git。
2.1 Node.js 的安装与版本检查
Claude Code 是通过 npm 分发的，所以 Node.js 是必须的。官方要求 Node.js 18 以上，我建议装 LTS 版本（长期支持版），比如当前的 Node.js 20 LTS 或 22 LTS。原因很简单，LTS 版本稳定，而且 Claude Code 这类工具更新快，对 Node 新特性有依赖，但也不会激进到要求最新版。
装 Node 的方式在 Windows 上有几种，最常见的两种。
第一种，直接去 Node.js 官网下载 Windows Installer（.msi）安装包，一路 Next 装完。这种方式最简单，适合绝大多数人。安装完会自动把 node 和 npm 加进 PATH。
第二种，用 winget 命令行安装，在 PowerShell 里执行：
powershell复制winget install OpenJS.NodeJS.LTS
无论用哪种方式，装完都要打开一个新的终端窗口，执行下面的命令确认版本：
powershell复制node -v
npm -v
如果 node -v 能输出 v20.x 类似的信息，说明安装成功。如果提示“node 不是内部或外部命令”，大概率是 PATH 没有生效，关掉终端重新开一个，或者重启一次电脑。顺便说一句，Windows 上 PATH 的修改需要新开的终端窗口才生效，别在那个已经开着的窗口里死等。
2.2 Git 的安装与配置
Claude Code 本身不强制要求 Git，但后面很多功能会用到。比如它要读取 git 历史来做变更分析、生成提交信息、对比 diff，这些操作都依赖 git 命令。如果你平时不怎么会 git，我的建议是仍然装上，成本不高，而且后面处理代码仓库的时候会省很多事。
Git 在 Windows 上的安装同样很简单，官网下载 Git for Windows，一路安装即可。安装时有一个选项是调整 PATH 环境的，默认选“Git from the command line and also from 3rd-party software”就行，这样在 PowerShell、CMD 里都能直接用 g