第一次在Windows下装Claude Code我走了不少弯路。图省事直接装在Windows端用是能用一碰真实项目就露馅脚本执行权限、路径分隔符、各种Unix小工具缺失各种别扭。后来老老实实把WSL2环境整理了一遍再在Ubuntu里装Claude Code才算找到舒服的姿势。这篇东西就是一次完整复盘从WSL2安装、Node.js部署、CLI登录到项目里真正跑起来一次性说清楚。适合刚接触WSL2的新手也适合已经装了但遇到“command not found”“EACCES”这类问题的人。1. 为什么是WSL2Windows用户装Claude Code的最优解1.1 原生Windows方案的几个别扭点Claude Code本质上是一个跑在终端里的开发者工具它背后要调用shell解释器、Git、grep、文件搜索这一整套Linux生态的东西。Windows上也有PowerShell和cmd也装了Git Bash但日常用起来跟真正的Linux环境还是差着一层。我实测下来最明显的三个别扭点一是路径。Windows路径是反斜杠加盘符Linux路径是正斜杠Claude Code这类工具在操作文件时经常要在两套路径规则之间来回切换稍微复杂点的脚本就报错。二是权限模型。Linux的权限体系跟Windows的NTFS权限完全是两套逻辑WSL2里一个chmod就能解决的问题在Windows原生环境里往往要找半天设置项。三是工具链。很多辅助工具比如ripgrep、zsh、tmux、rsync原生Windows装起来要么没有官方版本要么要经过一层兼容层总不如Linux下那么顺手。Claude Code的真实使用场景是处理整个代码仓库不是单文件对话。这意味着它要频繁读写文件、执行命令、看git diff。这类工具在贴近生产环境的Linux shell里跑稳定性和一致性会好很多。1.2 为什么不是WSL1而是WSL2老版本的WSL1是一个兼容层单纯把Linux系统调用翻译成Windows调用速度快但兼容性不够。WSL2是一个轻量级虚拟机有完整Linux内核系统调用兼容性大幅提升。对Claude Code这种要调用一堆子进程、文件监听、网络服务的工具来说WSL2才是正经环境。可以这样理解WSL1是翻译器WSL2是完整的模拟环境。翻译器虽然快但遇到生僻词就容易卡壳模拟环境虽然多付一点启动成本但几乎所有Linux程序都能原样跑。如果你想长期把Claude Code当成日常开发主力工具直接上WSL2不要在这个问题上省事。1.3 安装前置条件速查检查项要求说明Windows版本Win10 21H2及以上或Win11旧版本也能装但麻烦很多CPU虚拟化BIOS里开启Intel VT-x或AMD-V没开WSL2起不来内存建议16GB最低8GBWSL2会吃一部分内存磁盘建议至少留30GB可用空间系统加工具链加项目缓存检查虚拟化是否开启最简单的方式是打开任务管理器性能页签里看“虚拟化”是否显示“已启用”。如果显示禁用需要重启进BIOS打开相关选项这一步每个主板路径不一样直接搜自己的主板型号怎么开VT-x就行。2. 先把WSL2环境拉到能用的状态2.1 一条命令装好WSL2与Ubuntu新版Windows可以直接用管理员权限的PowerShell或终端执行wsl --install这条命令会把WSL功能、虚拟机平台组件、默认的Ubuntu发行版一起装好装完重启基本就能用。如果你不想用默认版本可以用下面的命令看可选发行版wsl --list --online然后指定安装wsl --install -d Ubuntu-24.04装完重启后Ubuntu会弹出首次初始化窗口让你创建一个Linux用户名和密码。这里创建的账号属于管理员组日常操作够用不需要一开始就用root。安装完之后检查一下版本wsl --list --verbose输出里VERSION那列必须显示2。如果显示1执行wsl --set-version Ubuntu-24.04 2转换需要一点时间别中途关机。2.2 进入Ubuntu后的基础配置首次进入Ubuntu终端第一件事就是更新系统源sudo apt update sudo apt upgrade -y然后装基础工具包sudo apt install -y git curl unzip zip build-essential ca-certificatesbuild-essential很多人会忽略但它包含编译工具链。Claude Code在安装或后续执行某些npm包的原生模块时如果系统里缺编译器会莫名其妙报错提前装好能省很多事。如果你发现WSL2占用内存太高可以在Windows用户目录下建一个.wslconfig文件写入[wsl2] memory8GB processors4 swap4GB改完后在PowerShell执行wsl --shutdown重启WSL配置才生效。这里的内存限制按自己机器实际内存调别设得太小导致编译直接爆内存。2.3 发行版装在哪个盘WSL2的虚拟磁盘默认放在C盘时间一长可能占用几十GB。如果C盘紧张建议把发行版迁移到D盘。流程不复杂wsl --shutdown wsl --export Ubuntu-24.04 d:\wsl\ubuntu.tar wsl --unregister Ubuntu-24.04 wsl --import Ubuntu-24.04 d:\wsl\ubuntu d:\wsl\ubuntu.tar注意用import方式恢复的发行版默认会以root用户登录重新进入后需要编辑/etc/wsl.conf加一行[user] default你的用户名然后wsl --shutdown再进来用户就恢复正常了。新手如果C盘空间还够建议先跳过迁移专注把Claude Code跑通减少变量。3. 用nvm部署Node.js运行环境3.1 为什么不用apt直接装nodeUbuntu的软件源里确实有nodejs但版本一般偏老而且通过apt装的node会把npm全局目录放在系统路径下后面安装Claude Code时很容易碰到权限报错。更推荐的方式是nvm它是装在用户目录下的node版本管理工具不需要sudo切换版本也方便。你可以把nvm理解成node环境的“多版本衣柜”想换哪个版本随时切不会把系统搞得一团乱。3.2 安装nvm在Ubuntu终端执行官方安装脚本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完脚本会往.bashrc里写入nvm的加载配置。新开的终端一般会自动加载如果当前终端还找不到nvm手动执行source ~/.bashrc然后验证command -v nvm有输出就说明nvm就绪。如果你用的是zsh而不是bash注意看安装脚本提示可能需要把.bashrc里的相关配置手动复制到.zshrc。3.3 安装LTS版本Node并验证nvm install --lts nvm alias default lts/*第二条命令是把默认node版本固定为最新的LTS版本避免以后新开终端切到奇怪的版本。验证node -v npm -v which nodewhich node输出应该指向~/.nvm/versions/node/vxx.x.x/bin/node。如果指向/usr/bin/node说明当前shell加载的是apt版本需要检查nvm是否正常加载。3.4 npm全局权限的替坑点用nvm管理node的最大好处是npm全局安装包默认放在用户目录下完全不需要sudo。如果你当初用apt装了node再直接npm install -g经常会报EACCES错误。很多人遇到这个错误就习惯性加sudo结果越弄越乱。正确做法是彻底切换到nvm管理的node然后把老的全局包清理掉。不建议去chown改/usr/lib/node_modules的权限那是在修补一个不该存在的问题。初次使用nvm的人还容易忽略一点安装Claude Code之前先确认当前终端已经加载了nvm的node。不同终端窗口可能环境不同最好统一用Windows Terminal打开Ubuntu避免环境不一致。4. 安装与登录Claude Code4.1 定位官方CLI包并全局安装Node环境就绪后Claude Code的安装其实就一条命令npm install -g anthropic-ai/claude-code这条命令会把Claude Code命令行工具安装到当前node版本的全局目录。安装完验证claude --version如果正常输出版本号安装成功。如果提示command not found跳到后面第6节排查。安装位置可以这样看npm prefix -g然后检查这个目录下的bin里有没有claude。卸载也很简单npm uninstall -g anthropic-ai/claude-codeClaude Code本身有自动更新机制启动时如果发现新版本会提示。网络环境正常的情况下直接按提示更新即可。4.2 首次登录与授权安装完成后在项目目录里执行claude第一次运行会进入登录流程。终端会提示你打开浏览器进行授权可能还要选择账号类型或API Key方式。我这里只讲订阅账号的常见路径浏览器打开授权页授权后回调到本地端口完成登录。WSL2默认会把Linux里监听的localhost端口转发到Windows所以大多数情况下浏览器可以正常打开回调地址授权会自动完成。如果你发现授权后终端没反应或者提示回调失败复制终端里给出的授权链接手动粘贴到Windows浏览器重新走一遍。如果一直卡住考虑是不是之前有过旧配置残留可以先把家目录下的.claude相关配置目录备份改名再重新登录。登录完成后进入交互界面直接输入问题测试claude看到正常响应就说明通了。4.3 配置项目级记忆与模型档位Claude Code支持把项目说明放在CLAUDE.md文件里放在项目根目录。它启动时会自动读取这个文件作为对整个项目的长期上下文。这相当于给AI一件“项目说明书”。一个典型的CLAUDE.md示例# 项目名称 这是一个Python编写的命令行工具核心逻辑在src目录下。 # 技术栈 Python 3.11、Click、pytest # 常用命令 - 运行测试: pytest tests/ - 打包: python -m build # 注意事项 - 不要修改migrations目录下的自动生成文件 - 提交前必须跑一遍pytest交互模式下可以用斜杠命令完成一些常规操作/help查看全部命令/config打开配置/model切换模型档位。如果你处理的任务很复杂选一个更高档位的模型会稳一点如果只是一些简单脚本改动用速度更快的档位成本更低也更高效。5. 在项目中真正用起来5.1 项目目录放哪/home 还是 /mnt/c这是一个非常影响体验的决策。WSL2访问Windows磁盘上的文件走的是9P协议对大量小文件的读写性能很差。如果你把项目放在/mnt/c/Users/xxx/project下直接让Claude Code处理遇到node_modules这种成千上万小文件的项目会很卡git操作也可能慢到怀疑人生。正确做法是把项目复制到WSL2自己的Linux文件系统里比如~/work。命令大致是这样mkdir -p ~/work rsync -av --exclude node_modules --exclude .git /mnt/c/Users/你的用户名/project/ ~/work/project/没有rsync就先sudo apt install rsync。复制到/home目录后再让Claude Code操作这个副本性能会好很多。Windows侧要打开这个项目文件可以用文件管理器访问\\wsl$\Ubuntu-24.04\home\你的用户名\work也可以直接在WSL终端里执行code .。5.2 交互式会话和单次提问进入项目目录cd ~/work/project claude交互模式下可以连续对话Claude Code能读取项目文件、执行命令、修改代码。比如你说“看一下这个模块的测试为什么挂帮我定位原因”它会自己去看测试文件、跑相关命令然后给出修改方案。想单次提问不进入交互界面可以加-p参数claude -p 用中文解释一下当前目录的代码结构这种模式适合写脚本调用比如在终端里快速问一句拿到结果就走。我的习惯是让Claude动手改代码之前先明确告诉它“先给方案不要改代码”。等它给出计划、你觉得靠谱了再允许它执行。这能避免它自作主张做出一堆你不想看的改动。5.3 与VS Code Remote-WSL打通在WSL终端里执行code .如果之前装过VS Code的Remote插件它会自动连接WSL发行版并打开当前目录。如果没有VS Code会提示安装Remote-WSL扩展装好后左下角会出现“WSL”图标说明当前窗口已经处于WSL环境。在VS Code的集成终端里直接跑claude跟在WSL外面是一样的。这个组合很舒服左边是代码编辑窗口下面是WSL终端和Claude Code对话修改的文件实时可见。5.4 给Claude Code加一层权限护栏Claude Code默认会用权限系统管理它能执行的操作。刚开始用的时候建议不要急着把权限全放开。一方面让AI帮你写代码确实爽另一方面高风险操作还是要留一手。我个人的用法是把代码文件读取和终端命令执行的权限放得宽一些但涉及删除文件、改写全局配置的操作尽量让它每次先征求确认。尤其不要因为懒得看提示就开跳过权限的运行模式一旦AI判断失误真删了重要文件后悔都来不及。6. 高频问题与排错实录6.1 安装后提示command not found最常发生在两个场景一是npm装完后全局bin目录不在PATH里二是之前apt也装过node系统里同时存在两套node环境。排查顺序很关键which claude command -v claude npm prefix -g如果npm prefix -g指向/usr说明当前用的还是系统node而不是nvmnvm没有正确加载。手动执行source ~/.bashrc新开一个终端窗口再试。如果npm prefix -g已经指向~/.nvm/...但which claude还是找不到检查该目录下面的bin里有没有claude没有就重新执行一次npm全局安装。6.2 安装报EACCES权限错误典型报错是npm在写/usr/lib/node_modules时没有权限。根因是node不是通过nvm装的而是通过apt装的npm全局目录落在系统路径里。不要加sudo硬装不要chown系统目录。干脆用nvm装一个自己的node然后重新安装Claude Code这个问题自然消失。如果之前已经用sudo装过部分包建议npm uninstall -g清理一下相关包再用正常用户重新装。6.3 登录授权一直无法完成WSL2的端口转发大多数时候正常但偶尔还是会碰到浏览器打不开回调地址的情况。这时候不要慌把终端给的完整授权链接复制到Windows浏览器里手动打开授权成功后回到终端看看是否显示成功。如果重复失败可能是旧登录状态污染可以先退出、备份配置目录再重新登录。还有一个容易忽略的点Claude Code授权过程中终端窗口不能关闭它要等回调结果。我见过有人一边授权一边把终端关了然后反复说登不上。6.4 在/mnt/c下操作明显卡顿这通常不是Claude Code的问题而是WSL2对Windows磁盘的访问延迟。项目里如果有大量小文件比如node_modules、缓存目录性能会非常差。解决方法是把项目迁到Linux文件系统重新安装依赖。如果项目必须放在Windows盘里至少让Claude Code的工作目录不要递归扫描整个庞大目录树把不相关的目录明确排除掉。6.5 版本更新失败或启动报错更新Claude Code可以重新执行一次全局安装。如果权限有问题检查一下npm config get prefix确认它在用户目录下而不是/usr。另一个常见问题是Windows终端字体或编码问题导致界面乱码。建议用Windows Terminal主题字体选一个支持UTF-8的等宽字体别用老旧的cmd窗口。6.6 问题速查表症状原因处理方式找不到claude命令nvm未加载或全局bin不在PATHsource ~/.bashrc新开终端重装CLInpm报EACCESnode来自apt全局目录在系统路径改用nvm管理node不要sudo硬装授权链接打不开localhost回调转发异常复制授权链接到Windows浏览器手动打开WSL2里跑项目很慢项目在/mnt/c下9P文件协议性能差把项目迁到~/work重装依赖更新后启动异常权限或缓存残留重新全局安装确认npm prefix在用户目录7. 我的使用习惯与一些建议7.1 先立“项目说明书”再开工我每个项目都会维护一份CLAUDE.md而且不是写一次就不管。项目里新增了模块、改了构建命令、换过测试框架都会同步更新这份文档。原因很简单Claude Code读这个文件就能少问很多基础问题回答也更贴合项目实际。你花在写说明上的时间会在后续每一次对话里赚回来。7.2 不要盲目放开全部权限AI写代码能力很强但判断力不等于零风险。我踩过一次坑让它重构一个工具脚本它顺手把另一个模块的兼容逻辑改了测试没跑全上线前才发现。从那以后我给自己定了一个规矩关键项目里让AI先出方案我看过diff再让它继续。权限粒度宁可保守一点也不要图一时爽快。7.3 把WSL2当成正经Linux服务器维护很多人装完WSL2只当玩一下用两天发现慢、乱、问题多就放弃了。其实WSL2就是一个完整的Linux环境该做的维护一样要做定期更新软件包、磁盘空间告警时清理旧版本node、项目配置备份。我习惯把.bashrc、CLAUDE.md和Claude Code的配置文件目录放进一个自己维护的备份目录换机器后很快能恢复同样的环境。最后分享一个小技巧如果你经常在shell里来回切换项目给claude起几个别名能省不少事。比如在.bashrc里加一行alias ccclaude这样实际敲命令时更顺手。装好只是开始环境理顺、权限管好、文档跟上Claude Code在WSL2里的体验会稳定很多。