1. 为什么 Windows 上跑 Claude Code 值得单独写一篇在 Mac 和 Linux 上装 Claude Code基本就是一行命令的事。但到了 Windows情况立刻变得复杂起来终端环境有 CMD、PowerShell、Windows Terminal、Git Bash 好几套Node.js 的安装方式有官方安装包、nvm-windows、fnm、WinGet 多种选择环境变量和 PATH 的继承规则又跟 Unix 系完全不一样。我见过太多人在 Windows 上折腾了一下午最后卡在claude命令找不到、或者终端里中文乱码、或者权限报错上。这篇内容就是把我自己在 Windows 上从零落地 Claude Code 的完整过程拆开讲清楚。Claude Code是 Anthropic 推出的命令行 AI 编程助手它能直接读写你本地的项目文件、执行终端命令、跑测试、改代码本质上是一个跑在终端里的智能编程代理。它适合所有想在 Windows 上把 AI 编程助手真正用起来的开发者不管你是刚接触命令行的小白还是已经用惯了 WSL 的老手都能从这篇里找到能直接抄的配置方案。我会覆盖三条安装路线WinGet、npm、原生安装器、终端选型、环境变量配置、VS Code 集成、以及我自己踩过的七八个坑。全程基于 Windows 11 实测Windows 10 22H2 及以上版本同样适用。先把结论放前面最省心的组合是 Windows Terminal PowerShell 7 WinGet 安装 Node.js npm 全局装 Claude Code后面会详细解释为什么这么选。2. 装之前先把这几个前置条件理清楚2.1 Node.js 版本这道坎绕不过去Claude Code 是基于 Node.js 运行的工具对 Node 版本有硬性要求。实测下来Node.js 18 LTS 是底线推荐直接上 20 LTS 或 22 LTS。低于 18 的版本会在启动时直接报错退出而且报错信息不一定明确告诉你版本太低可能是一堆看不懂的语法错误。为什么版本这么关键因为 Claude Code 内部用到了较新的 JavaScript 语法特性和一些 Node 原生模块的能力老版本 Node 的 V8 引擎不支持这些特性。这就像你拿一把十年前的老钥匙去开新换的锁齿形对不上。检查当前版本很简单打开 PowerShell 敲node -v npm -v如果显示v18.x.x以上就没问题。如果提示不是内部或外部命令说明 Node.js 根本没装或者没进 PATH那就往下看安装部分。注意如果你之前用官方 msi 安装包装过 Node又想换成 nvm-windows 管理多版本一定要先把旧版本从应用和功能里卸载干净再删掉残留的C:\Program Files\nodejs目录和用户目录下的.npmrc否则 nvm 切换版本时会各种冲突。2.2 终端的选择直接决定体验上限Windows 上的终端选择比很多人想象的重要。CMD 太老不支持很多现代特性PowerShell 5.1系统自带那个蓝色窗口虽然能用但对 UTF-8 的支持有坑Git Bash 是 Unix 风格但和 Windows 原生工具的路径混用容易出问题。我的建议很明确装 Windows Terminal配合 PowerShell 7。Windows Terminal 是微软官方的现代终端支持多标签、分屏、GPU 渲染、完整的 UTF-8在 Microsoft Store 里直接搜就能装。PowerShell 7 是跨平台的新版 PowerShell和系统自带的 5.1 是两个东西它对 UTF-8 和现代命令行工具的支持好得多。装 PowerShell 7 最省事的方式还是 WinGetwinget install --id Microsoft.PowerShell --source winget装完之后在 Windows Terminal 里把默认配置文件设成 PowerShell 7这一步很关键因为 Claude Code 在 PowerShell 7 下的表现明显比 5.1 稳定尤其是处理中文路径和输出的时候。2.3 网络与账号提前准备好省得中途卡壳Claude Code 需要连接 Anthropic 的服务所以你得有一个可用的账号并且完成 API 相关的配置。这部分我不展开讲具体账号细节但提醒一点先把账号和认证方式准备好再开始装工具。很多人是装完工具才发现登录不了然后又回头折腾来回切换很浪费时间。另外Windows 防火墙偶尔会拦截 Node.js 进程的网络请求第一次运行时如果弹出防火墙提示记得允许。如果公司网络有代理需要提前配好HTTP_PROXY和HTTPS_PROXY环境变量这个后面配置章节会讲。3. 三条安装路线我为什么最终推荐 WinGet 打底3.1 路线一WinGet 安装 Node.js推荐打底WinGet 是 Windows 官方的包管理器Windows 11 自带Windows 10 需要从 Store 装一下应用安装程序。用它装 Node.js 的好处是版本管理干净、升级方便、卸载彻底。winget install OpenJS.NodeJS.LTS这条命令装的是最新的 LTS 版本。装完之后必须重开一个终端窗口因为 PATH 环境变量的更新不会自动同步到已经打开的终端里。这是新手最常踩的坑装完了在当前窗口敲node -v还是提示找不到命令以为装失败了其实只是没重开窗口。验证一下node -v npm -v两个都能正常输出版本号说明 Node 环境就绪。WinGet 装的好处是以后升级直接winget upgrade OpenJS.NodeJS.LTS就行不用手动去官网下安装包。3.2 路线二npm 全局安装 Claude CodeNode 就绪之后装 Claude Code 本体就一行npm install -g anthropic-ai/claude-code这里的-g是全局安装意思是装到系统级别的 npm 全局目录里这样在任何路径下都能直接敲claude命令调用。如果你不加-g它只会装到当前项目的node_modules里换个目录就用不了。装完之后验证claude --version能输出版本号就成功了。如果提示claude不是可识别的命令八成是 npm 全局目录没进 PATH。查一下全局目录在哪npm config get prefix正常情况下这个路径比如C:\Users\你的用户名\AppData\Roaming\npm应该在系统 PATH 里。如果没有手动加进去然后重开终端。实操心得npm 全局安装偶尔会因为网络问题卡住或报ETIMEDOUT。这时候先换 npm 镜像源再重试npm config set registry https://registry.npmmirror.com装完可以再换回来。这个镜像源在国内环境下稳定性好很多。3.3 路线三原生安装器与在线升级除了 npmClaude Code 也提供了原生安装方式适合不想依赖 Node 全局环境的场景。另外它支持在线升级命令是claude update或者用 npm 重新装最新版npm install -g anthropic-ai/claude-codelatest我个人的习惯是用 npm 装用 npm 升级保持一条链路清晰。混用安装方式比如先用原生安装器又用 npm 覆盖容易导致版本混乱出现明明升级了但版本号没变的诡异情况。如果你遇到这种问题先npm uninstall -g anthropic-ai/claude-code卸干净再重新装。三条路线的对比如下安装方式适合人群优点缺点WinGet 装 Node npm 装 Claude大多数 Windows 用户链路清晰、升级方便需要先配好 Node原生安装器不想装 Node 全局环境独立、干净升级路径不同nvm-windows npm需要多 Node 版本切换版本隔离好配置稍复杂4. 环境变量与终端配置让 claude 命令真正听话4.1 PATH 配置的完整排查链路claude命令找不到是 Windows 上最高频的问题。我把完整排查链路给你捋一遍照着走基本都能解决。第一步确认 npm 全局目录npm config get prefix第二步确认这个目录在不在 PATH 里。在 PowerShell 里查$env:Path -split ; | Select-String npm如果没有输出说明没配。手动添加有两种方式图形界面走系统属性 → 环境变量 → 用户变量 → Path → 新建把 npm 全局目录粘进去命令行方式需要管理员权限的 PowerShell[Environment]::SetEnvironmentVariable(Path, $env:Path ;C:\Users\你的用户名\AppData\Roaming\npm, User)第三步重开终端。PATH 的修改对已打开的终端无效这一步反复强调是因为它真的太容易被忽略。第四步如果还不行检查是不是有多个 Node 版本冲突。用where.exe node看看系统里到底有几个 node.exe如果出现多个路径说明旧版本没卸干净需要清理。4.2 中文乱码与编码问题Windows 终端默认编码有时候不是 UTF-8导致 Claude Code 输出中文时乱码。解决办法是在 PowerShell 7 的配置文件里设置编码。先找到配置文件路径$PROFILE如果文件不存在就创建然后加入[Console]::OutputEncoding [System.Text.Encoding]::UTF8 $OutputEncoding [System.Text.Encoding]::UTF8保存后重开终端。这样 Claude Code 输出的中文、以及你输入的中文路径都能正常显示。这个坑我在处理带中文目录名的项目时踩过乱码会让你完全看不懂 AI 在说什么。4.3 代理与网络环境变量如果你的网络环境需要走代理给 Claude Code 配环境变量。在 PowerShell 里临时设置当前窗口有效$env:HTTP_PROXY http://127.0.0.1:端口 $env:HTTPS_PROXY http://127.0.0.1:端口想永久生效就写进系统环境变量或者写进$PROFILE。注意端口要换成你自己实际使用的。配完之后可以用claude启动测试连接是否正常。注意代理配置只影响网络请求路径不要在里面填任何账号密码明文尤其是共享电脑上。用系统级的凭据管理更稳妥。5. 和 VS Code 打通在编辑器里直接用 Claude Code5.1 安装扩展与终端集成Claude Code 有官方的 VS Code 扩展装完之后可以在编辑器内的集成终端里直接调用省得来回切窗口。在 VS Code 扩展市场搜 Claude Code 安装即可或者用命令行code --install-extension anthropic.claude-code装完之后在 VS Code 里按Ctrl打开集成终端确保这个终端用的是 PowerShell 7在终端下拉菜单里选。然后直接敲claude就能在项目根目录启动。为什么强调在项目根目录启动因为 Claude Code 会以当前工作目录作为项目上下文它会读取这个目录下的文件、理解项目结构。如果你在错误的目录启动它看到的项目就是错的给出的建议自然也不对。5.2 让 Claude Code 直接执行终端命令Claude Code 的一个核心能力是直接执行终端命令。比如你让它跑一下测试它会自己调用npm test或pytest读取输出然后根据结果决定下一步。这个能力在 Windows 上要注意几点第一确保你的默认 shell 配置正确。Claude Code 执行命令时会调用系统默认 shell如果默认是 CMD 而你的项目脚本是 bash 语法就会失败。可以在设置里指定用 PowerShell 或 Git Bash。第二涉及权限的命令比如需要管理员的操作会失败因为 Claude Code 继承的是当前终端的权限。需要提权的操作还是得你自己在管理员终端里手动做。第三路径分隔符。Windows 用反斜杠\Unix 用正斜杠/。Claude Code 一般能自动处理但你在给它指令时用正斜杠通常更保险因为很多跨平台工具认正斜杠。5.3 项目级配置文件的写法在项目根目录放一个配置文件可以让 Claude Code 记住这个项目的特定规则。比如告诉它用哪个测试命令、代码风格是什么、哪些目录不要动。这个文件通常叫CLAUDE.md放在项目根目录。一个实用的CLAUDE.md大概长这样# 项目说明 这是一个 Node.js TypeScript 项目。 ## 常用命令 - 安装依赖npm install - 跑测试npm test - 构建npm run build ## 代码规范 - 使用 2 空格缩进 - 提交前必须通过 lint ## 注意事项 - 不要修改 config/ 目录下的文件 - 数据库迁移脚本在 migrations/ 下有了这个文件每次启动 Claude Code 它都会先读一遍省去你反复解释项目背景的功夫。这是提升效率的关键一步很多人装完就用默认配置其实浪费了很大的定制空间。6. 我在 Windows 上踩过的坑与对应解法6.1 权限报错non-elevated terminal 相关提示有一类报错跟终端权限有关提示大意是需要从非提权终端启动守护进程或者反过来需要提权。这类问题的根源是 Windows 的 UAC 权限模型和 Unix 完全不同。在 Unix 里sudo是显式的Windows 里权限是跟着终端进程走的。我的处理原则是日常开发一律用普通权限终端只有明确需要改系统配置、装全局服务时才开管理员终端。Claude Code 本身不需要管理员权限用管理员终端跑反而可能因为权限过高导致文件属主混乱。如果你看到权限相关的报错先确认是不是在管理员窗口里跑的换普通窗口试试。6.2 端口占用与进程清理开发过程中经常遇到端口被占用比如 Claude Code 帮你启动的某个服务端口没释放。Windows 上查端口占用的命令netstat -ano | findstr :3000最后一列是进程 PID然后taskkill /PID 进程号 /F/F是强制结束。这个组合在 Windows 上清理占用端口的僵尸进程特别管用。我建议把这两条命令记下来比去任务管理器里翻快得多。6.3 脚本闪退与输出丢失Windows 上跑脚本偶尔会闪退窗口一闪就没了看不到任何输出。这通常是因为脚本执行完立即退出或者报错后窗口自动关闭。解决办法是在脚本末尾加pause或者从已经打开的终端里手动执行脚本而不是双击运行。对于 Claude Code 执行的命令如果输出被截断可以在命令后面加21把错误输出也重定向到标准输出这样报错信息不会丢。排查问题时这个技巧很实用。6.4 升级后版本没变的诡异情况前面提过混用安装方式会导致升级无效。还有一种情况是 npm 缓存导致的。如果claude update之后版本号没变试试清缓存再装npm cache clean --force npm install -g anthropic-ai/claude-codelatest另外检查一下是不是有多个 claude 可执行文件在不同路径用where.exe claude看看如果有多个把旧的删掉。7. 把 Claude Code 用顺手的几个进阶习惯7.1 用 WSL2 还是纯 Windows我的取舍很多人纠结要不要在 WSL2 里跑 Claude Code。我的看法是如果你的项目本身就是 Linux 环境比如要用 Docker、要跑 shell 脚本、依赖 Linux 特有的工具链那就在 WSL2 里跑体验更接近生产环境。但如果你的项目是纯 Windows 开发比如 .NET、Windows 桌面应用那就在原生 Windows 里跑别绕 WSL。WSL2 的一个注意点是文件系统性能。把项目放在 WSL 的 Linux 文件系统里/home/...比放在 Windows 挂载盘/mnt/c/...里快很多因为跨文件系统的 IO 开销大。如果你在 WSL 里跑 Claude Code项目文件也放 Linux 侧速度差别很明显。7.2 让 AI 少走弯路的提示词习惯Claude Code 的能力上限很大程度取决于你怎么跟它说话。几个我总结的习惯第一给上下文而不是给命令。与其说帮我改这个函数不如说这个函数在处理空数组时会崩帮我加上边界检查保持现有代码风格。后者它一次就能改对。第二让它先读再改。对于不熟悉的代码先让它读一下这个文件告诉我它的作用确认它理解对了再让它动手。这能避免它基于错误理解乱改一通。第三善用项目配置文件。前面说的CLAUDE.md就是干这个的把项目约定写进去比每次口头交代高效得多。7.3 版本管理与回滚意识让 AI 改代码之前确保你的工作区是干净的或者先提交一次。这样万一改坏了git checkout一下就能回滚。我吃过亏让 Claude Code 重构一个模块它改了一大片结果发现方向不对又没提交只能手动一个个还原。养成习惯动手前git status看一眼有未提交的改动先 commit 或 stash。这是用任何 AI 编程工具都应该有的基本操作纪律。8. 常见问题速查把高频问题整理成表遇到直接对号入座现象最可能的原因解决方向claude命令找不到npm 全局目录没进 PATH查npm config get prefix加进 PATH 后重开终端装完 node 命令无效没重开终端关闭当前窗口重新打开中文输出乱码终端编码非 UTF-8在$PROFILE里设 UTF-8 编码网络请求超时未配代理或镜像源配HTTPS_PROXY或换 npm 镜像源升级后版本没变缓存或多版本冲突清缓存、where.exe claude查重复执行命令权限不足终端权限不够换普通终端或对特定操作单独提权端口被占用僵尸进程未释放netstat -ano查 PID 后taskkill这张表基本覆盖了 90% 的日常问题。遇到没列出来的先看 Claude Code 自己的报错信息它通常会说清楚是哪一步出的问题比盲目搜索快。9. 最后分享几个我压箱底的小技巧用了一段时间之后有几个习惯让我的效率提升明显顺手分享出来。第一个是给常用操作做别名。在 PowerShell 的$PROFILE里加几行比如function cc { claude }以后敲cc就能启动。或者把常用的项目路径做成快捷函数一键 cd 过去再启动 Claude Code。第二个是善用 Windows Terminal 的分屏。左边开一个 Claude Code右边开一个跑测试或看日志的终端改完代码立刻验证不用来回切窗口。这个工作流一旦习惯就回不去了。第三个是定期清理 npm 全局缓存。Windows 上 npm 缓存目录时间长了会很大偶尔npm cache clean --force一下能避免一些莫名其妙的安装失败。第四个是把报错信息完整复制给 Claude Code。它排查问题的能力很强但前提是你给它完整的错误堆栈。很多人只贴最后一行信息不够它只能猜。把完整的报错、你执行的命令、期望的结果一起给它解决速度快很多。Windows 上跑 Claude Code 这件事说难不难说简单也不简单关键是把 Node 环境、终端、PATH 这几块理顺。理顺之后它就是一个非常顺手的编程助手。我自己的体会是前期花半小时把环境配扎实后面能省下几十个小时的折腾。