Claude Code 在 Windows 怎么装？原生 vs WSL 报错排查

在 Windows 上装 Claude Code 比 macOS 多一层坑：它原生是为类 Unix 环境设计的命令行工具，到了 Windows 就要在原生安装和 **WSL（Windows Subsystem for Linux）**两条路之间做选择。这篇讲清两条路怎么选、Node 与 PATH 怎么配、PowerShell 执行策略和路径分隔这些高频报错怎么排查。装不上、装完跑不起来的，基本都能在这里对号入座。

原理：为什么 Windows 装它总卡壳

Claude Code 是一个用 Node.js 写的 CLI（命令行）工具，通过 npm 全局安装。它的卡壳点有三个固定来源，机制不变，只是各家环境表现不同：

1. Node 环境：它依赖一个较新版本的 Node.js（具体最低版本以官方文档为准），系统里 Node 太旧或根本没装，就会在安装或启动时报错。
2. PATH 没生效：npm 全局安装的命令要写进系统 PATH 才能直接敲 claude 调用。Windows 的 PATH 配置和 npm 全局目录经常对不上，导致”装了但找不到命令”。
3. 类 Unix 假设：工具内部会调用一些类 Unix 的 shell 行为（路径用 / 分隔、依赖 git bash 等）。原生 Windows 的 cmd/PowerShell 与之有摩擦，这就是为什么很多人最后选 WSL。

搞清这三点，下面的报错就都不是玄学了。

原生 vs WSL：先选对路

两条路都能跑通，但适用人群不同：

你的情况	推荐	原因
想最省事、对 Linux 不抵触	WSL	类 Unix 环境，工具按预期运行，坑最少
项目代码就在 Windows 盘、不想折腾子系统	原生安装	直接操作 Windows 文件，无跨系统路径问题
团队/教程都用 WSL，要对齐	WSL	少踩别人没踩过的坑，求助有人懂
公司机器禁止开 WSL/Hyper-V	原生安装	没得选，按原生流程配 git bash

一句话结论：拿不准就上 WSL，它是官方与社区踩坑最少的路；只有当你的代码必须留在 Windows 文件系统、或环境不允许开子系统时，才走原生。

路线一：WSL 安装（推荐）

WSL 让你在 Windows 里跑一个真正的 Linux，Claude Code 在里面就跟在 Linux 上一样自然。

1. 启用并安装 WSL：用管理员 PowerShell 执行 wsl --install，按提示装好默认的 Linux 发行版（通常是 Ubuntu），重启后设置用户名密码。
2. 进 WSL 装 Node：在 WSL 终端里装 Node.js，强烈建议用 nvm 管理版本（见下方”用 nvm 装 Node”）。
3. 全局安装 Claude Code：用 npm 全局安装官方包（包名以官方文档为准），装完敲 claude 验证。
4. 在 WSL 里打开项目：把代码放在 WSL 的 Linux 文件系统里（如 ~/projects/）性能最好；要访问 Windows 盘可走 /mnt/c/...，但跨系统读写会慢。

关键提醒：别在 WSL 里调用 Windows 的 Node。如果 which node 指向 /mnt/c/...，说明它用的是 Windows 那个 Node，会引发各种路径错乱——在 WSL 内单独装一套 Node。

wsl --install 卡住或失败怎么办

这一步最常见的三种翻车，按出现频率排：

1. 提示”虚拟化未启用”：进 BIOS/UEFI 打开 Intel VT-x 或 AMD-V（部分品牌机在”Advanced”或”CPU Configuration”菜单里，找不到就搜主板型号 + “开启虚拟化”）。开完保存重启，回到 Windows 再跑一次 wsl --install。
2. 企业电脑装了组策略限制：公司 IT 统一管控的机器，wsl --install 会直接报权限错误或者装到一半卡死。这种情况别自己硬刚，找 IT 申请开通 WSL 功能，比自己折腾组策略省时间。
3. 默认装的是 WSL 1，性能拉胯：跑 wsl -l -v 看版本号，如果显示 1 就升级：wsl --set-version Ubuntu 2（把 Ubuntu 换成你实际的发行版名）。WSL 2 用的是真正的 Linux 内核，文件系统和网络性能都比 WSL 1 好一截，Claude Code 装在 WSL 1 里偶尔会遇到诡异的文件监听失效问题。

装完之后如果整机内存占用异常高（vmmem 进程吃几个 G），在用户目录（C:\Users\你的用户名\）建一个 .wslconfig 文件，写入：

[wsl2]
memory=4GB
processors=4

限制住 WSL 2 的资源上限，改完在 PowerShell 里 wsl --shutdown 重启一次生效。

路线二：原生 Windows 安装

不想用 WSL 就走原生，核心是装好 Node + 配好 git bash。

1. 装 Node.js：从官方安装包装一个较新版本的 Node，或用 nvm-windows 管理（注意 nvm-windows 与 Linux 的 nvm 是两个不同项目）。
2. 配好 git bash：装 Git for Windows，它自带的 git bash 提供类 Unix shell。Claude Code 在原生 Windows 上常需要它来执行内部命令，没装 git bash 是原生路最常见的失败原因。
3. npm 全局安装：在终端里全局安装官方包，确认 npm 全局目录在 PATH 里（见下方排查）。
4. 优先在 git bash 里运行：直接在 git bash 终端里敲 claude，比在 cmd/PowerShell 里少很多路径分隔的麻烦。

用 nvm 装 Node（两条路都建议）

直接装系统级 Node，日后升级、切版本都难受。用 nvm 把 Node 版本管起来是更省心的做法：

• WSL / Linux / macOS：用 nvm（nvm-sh 项目），nvm install --lts 装长期支持版，nvm use 切换。
• 原生 Windows：用 nvm-windows（coreybutler 项目），命令类似但是独立工具。

用 nvm 的好处：Claude Code 要求的 Node 版本变了，nvm install 一条命令就升级，不污染系统、不用卸了重装。装完务必重开终端，让 nvm 写入的 PATH 生效。

具体命令举个例子（WSL / Linux 下）：

nvm install --lts
nvm use --lts
nvm alias default node   # 把当前版本设为默认，新开终端不用再手动 use

装完敲 node -v 确认版本号，再 npm install -g 装 Claude Code 的包。这里有个新手常踩的坑：装完 nvm 之后如果 node -v 还是显示系统自带的旧版本，说明 shell 配置文件（~/.bashrc 或 ~/.zshrc）里 nvm 的初始化代码没生效，重开一个全新的终端窗口（不是标签页）通常就能解决；还不行就手动跑一遍 source ~/.bashrc。

原生 Windows 下用 nvm-windows 类似：nvm install lts、nvm use <版本号>（nvm-windows 的 use 要写具体版本号，不支持 --lts 这种写法，这也是它和 Linux 版 nvm 命令不完全对齐的地方之一）。

npm 全局安装报权限错误（EACCES / EPERM）

WSL/Linux 下如果 npm 全局安装报 EACCES: permission denied，别用 sudo npm install -g 强行绕过——这会把全局目录的属主改成 root，以后每次装包都要 sudo，越搞越乱。正确做法是改 npm 的全局安装目录到用户自己的目录：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

然后把 ~/.npm-global/bin 加进 ~/.bashrc 的 PATH 里，重开终端。原生 Windows 下类似的报错通常是杀毒软件或 Windows Defender 把 npm 写文件的动作当成可疑行为拦了，把项目目录和 npm 全局目录加进杀毒软件的信任/排除列表就能解决，装之前先临时关一下实时防护排查是不是这个原因。

公司内网走代理，npm 装不上包

在有代理的公司网络里，npm 请求会超时或直接失败。先确认代理配置对不对：

npm config set proxy http://你的代理地址:端口
npm config set https-proxy http://你的代理地址:端口

如果公司用的是国内镜像源（比如淘宝镜像），改用 npm config set registry https://registry.npmmirror.com 通常比配代理更省事、速度也更快。装完 Claude Code 之后记得改回官方源（npm config set registry https://registry.npmjs.org），避免以后其他包因为镜像同步延迟装到旧版本。

PowerShell 执行策略：装完跑不了脚本

在原生 PowerShell 里，npm 的命令是 .ps1 脚本，默认的执行策略（Execution Policy）会拦截脚本运行，表现为敲 claude 报”无法加载文件……因为在此系统上禁止运行脚本”。

解法是放宽当前用户的执行策略（不需要管理员，只影响你自己）：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

RemoteSigned 允许本地脚本运行、只对网上下载的未签名脚本设限，是兼顾安全与可用的常用档位。改完重开 PowerShell 再试。用 WSL 或 git bash 的不受这条限制——这也是它们更省心的原因之一。

怎么验证装成功

不管走哪条路，三步自检：

1. Node 在不在：node -v 和 npm -v 都能打印版本号。
2. 命令找得到：claude --version（或 claude -v）能打印版本，不报”command not found / 不是内部或外部命令”。
3. 能起会话：在一个项目目录里敲 claude，能进入交互界面、读到当前目录文件，就算真正跑通。

三步全过，才算装好；只装上不验证，往往是”以为好了，一用就崩”。

常见坑与排查

报错现象	原因	解法
command not found / 不是内部或外部命令	npm 全局目录不在 PATH	用 npm config get prefix 查全局目录，把它（及 /bin）加进系统 PATH，重开终端
装/启动时报 Node 版本过低	系统 Node 太旧	用 nvm 装较新 LTS（具体版本以官方文档为准），nvm use 切过去
PowerShell 报”禁止运行脚本”	执行策略拦截	Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
路径报错、找不到文件、\ 被当转义	Windows 用 \ 分隔、工具按 / 解析	在 git bash/WSL 里运行；路径统一用 /；含空格的路径加引号
原生下内部命令执行失败	没装 git bash	装 Git for Windows，在 git bash 终端里跑
WSL 里行为诡异、版本对不上	误用了 /mnt/c 下的 Windows Node	在 WSL 内单独装 Node，which node 不应指向 /mnt/c

排查口诀：先看 node -v，再看 claude 找不找得到，最后看是不是 shell/路径问题——九成的 Windows 安装故障都落在这三层。更细的报错信息和卡点，可对照 Claude Code 安装失败怎么解决（规划中）逐项排查。

常见问题

Windows 装 Claude Code 必须用 WSL 吗？ 不是必须。原生 Windows 也能装，配好 Node 和 git bash 即可。但 WSL 是类 Unix 环境、坑最少，新手优先选 WSL。

为什么敲 claude 提示”不是内部或外部命令”？ npm 全局安装目录没进系统 PATH。用 npm config get prefix 查出目录，加进 PATH 后重开终端。这是 Windows 上最高频的安装故障。

Windows 上路径里的反斜杠总报错怎么办？ Windows 用 \ 分隔，而工具按类 Unix 的 / 解析。最省事的做法是在 git bash 或 WSL 里运行，路径统一写 /，含空格的路径用引号包起来。

nvm 和 nvm-windows 是同一个东西吗？ 不是。Linux/WSL/macOS 用的 nvm（nvm-sh）和 Windows 原生的 nvm-windows（coreybutler）是两个独立项目，命令相近但不通用，别混装。

装好之后想系统地上手用法、跑通第一个真实任务，接着看 Claude Code 入门教程，从安装到实战连成一条线。

👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。