1. 为什么要在 Windows 上认真折腾 Claude Code
先说结论：Claude Code 在 Windows 上的体验，跟 macOS、Linux 相比确实要多花点心思，但绝对没到"劝退"的程度。我自己前前后后在 Windows 11 上装过五六次，从最初的 PowerShell 乱码、Node 版本冲突，到后来把 WSL2 和原生 Windows 两套方案都跑通，踩的坑基本能写一本小册子。这篇就把这些经验一次性摊开讲清楚。
Claude Code 是 Anthropic 推出的命令行 AI 编程助手，它跟普通的聊天式 AI 最大的区别在于：它能直接读写你本地的文件、执行终端命令、跑测试、改代码，是一个真正"能动手"的编程代理。你在终端里敲一句"帮我把这个项目的 ESLint 报错全修了"，它就会自己去读文件、改代码、跑 lint 验证，整个过程你只需要在旁边看着。这种能力对日常开发效率的提升是实打实的，尤其是处理那些重复性高、逻辑琐碎的活儿。
那为什么 Windows 用户要专门看这篇？因为 Claude Code 官方主推的是 macOS 和 Linux 环境，Windows 原生支持是后来才逐步完善的。早期版本在 Windows 上跑，经常遇到路径分隔符问题、PowerShell 编码问题、权限问题，还有 Node.js 环境配置的各种幺蛾子。这些问题不是不能解决，而是散落在各个 issue 和论坛里，新手很容易卡在第一步就放弃了。
这篇内容适合三类人：一是完全没接触过 Claude Code、想在 Windows 上从零开始的开发者；二是装过但被各种报错劝退、想彻底搞明白问题根源的人；三是已经在用但想优化体验、把 WSL2 和原生方案都摸透的老手。我会把安装配置的每一步、每个参数背后的逻辑、以及那些文档里不会写的坑，全部讲清楚。核心关键词就几个：Windows、Claude Code、安装配置、避坑优化、PowerShell，围绕这几个词展开，不跑题。
2. 装之前先想清楚：原生 Windows 还是 WSL2
2.1 两套方案的本质区别
在 Windows 上跑 Claude Code，你有两条路：一是直接在原生 Windows 环境里装，用 PowerShell 或 CMD 跑；二是装 WSL2（Windows Subsystem for Linux），在 Linux 子系统里跑。这两条路不是"哪个更好"的问题，而是"哪个更适合你的工作流"。
原生 Windows 方案的优势是轻量、直接。你不用额外装一个 Linux 子系统，不用管 WSL 和 Windows 之间的文件系统映射，Claude Code 直接操作你 Windows 上的项目文件，路径就是C:\Users\xxx\project这种，所见即所得。缺点是某些依赖 Linux 工具链的命令会跑不通，比如一些 shell 脚本、grep、sed这类工具，虽然 Git Bash 能补一部分，但总归不是原生的。
WSL2 方案的优势是环境完整。你相当于在 Windows 里跑了一个真正的 Linux，Claude Code 在里面跑跟在 Ubuntu 服务器上跑没区别，所有 Linux 工具链都能用。缺点是文件系统性能有损耗——如果你把项目放在 Windows 盘（比如/mnt/c/...），读写速度会明显变慢；如果放在 WSL 内部的文件系统（/home/xxx/...），速度正常但跟 Windows 侧的编辑器配合又有点别扭。
2.2 我的选择建议
我自己的做法是：主力用 WSL2，但项目文件放在 WSL 内部文件系统，编辑器用 VS Code 的 Remote-WSL 插件连过去。这样既拿到了完整的 Linux 环境，又避免了跨文件系统的性能损耗，VS Code 的体验也跟原生没差别。如果你只是偶尔用用、项目也不复杂，那原生 Windows 方案完全够用，别折腾。
判断标准很简单，看你的项目依赖：
| 场景 | 推荐方案 | 理由 |
|---|---|---|
| 纯前端项目（Vue/React） | 原生 Windows | 依赖 Node 生态，Windows 支持完善 |
| Python 数据/后端项目 | WSL2 | 很多库在 Linux 上更顺，虚拟环境管理更规范 |
| 需要跑 shell 脚本的项目 | WSL2 | 原生 Windows 跑 bash 脚本容易出问题 |
| 只是想让 AI 帮忙改改代码 | 原生 Windows | 轻量，不用装子系统 |
| 团队统一用 Linux 开发 | WSL2 | 环境一致，避免"我这能跑你那不能跑" |
提示：如果你选了 WSL2，记得把 WSL 装到非系统盘（比如 D 盘），具体方法后面会讲。系统盘空间紧张的话，这一步很关键。
2.3 硬件和系统的最低要求
不管选哪套方案，先确认你的机器达标：
- 系统版本：Windows 10 版本 2004 及以上，或者 Windows 11。WSL2 需要这个版本起步，老版本只能用 WSL1，体验差很多。
- 内存：建议 16GB 起步。Claude Code 本身不重，但同时开着 VS Code、浏览器、Docker 的话，8GB 会很吃力。
- 磁盘：至少留 20GB 空闲。WSL2 的虚拟磁盘会随着使用增长，别等到满了才想起来清理。
- Node.js：Claude Code 是基于 Node 的，需要 Node 18 或更高版本。这个后面单独讲。
3. 原生 Windows 方案：从零到跑通
3.1 Node.js 环境准备（别用系统自带的）
第一步永远是 Node.js。这里有个大坑：千万别去官网下那个.msi安装包直接装。不是说不能用，而是它会把 Node 装到C:\Program Files\nodejs，全局包也装在那个目录下，一旦你要切换 Node 版本、或者权限出问题，改起来非常麻烦。
我推荐用nvm-windows（Node Version Manager for Windows）来管理 Node 版本。这东西的好处是：你可以同时装多个 Node 版本，一条命令切换，全局包跟着版本走，互不干扰。装法也简单：
- 去 nvm-windows 的 GitHub Releases 页面下载
nvm-setup.exe。 - 安装时注意两个路径：nvm 自己的安装路径（建议
C:\Users\你的用户名\nvm），以及 Node 的 symlink 路径（建议C:\Users\你的用户名\nodejs）。这两个路径别搞混。 - 装完后打开新的PowerShell 窗口（重要，旧窗口读不到新环境变量），敲
nvm version确认装好了。 - 敲
nvm install 20装 Node 20 LTS，然后nvm use 20切换过去。 - 敲
node -v和npm -v验证。
这里有个细节：nvm-windows 切换版本时，如果提示exit status 1: Access is denied，多半是因为你之前用管理员权限装过 Node，或者nodejs那个 symlink 目录被占用。解决办法是把C:\Program Files\nodejs删掉（如果存在），然后以管理员身份重开 PowerShell 再nvm use。
注意：nvm-windows 和 nvm（macOS/Linux 那个）不是同一个东西，命令有差异。比如 nvm-windows 没有
nvm alias default，切换版本就是nvm use。
3.2 安装 Claude Code 本体
Node 环境搞定后，装 Claude Code 就一行命令：
npm install -g @anthropic-ai/claude-code但这一行背后有几个坑要提前说：
坑一：全局安装权限。如果你没配好 nvm，用系统 Node 装全局包，可能会报EACCES或EPERM权限错误。用 nvm 管理的话基本不会遇到，因为全局包目录在你用户目录下，不需要管理员权限。
坑二：npm 源太慢。国内直连 npm 官方源装这个包，可能会卡住或者超时。可以临时切到国内镜像：
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com装完后敲claude --version，能输出版本号就说明装好了。如果提示claude : 无法将"claude"项识别为 cmdlet...，那是 PATH 没配好，检查 nvm 的 symlink 目录有没有加到系统 PATH 里。
3.3 PowerShell 乱码问题的根治
这是 Windows 用户遇到最多的坑，没有之一。表现是：Claude Code 输出中文时显示成乱码，或者终端里出现一堆锟斤拷之类的字符。根源在于PowerShell 的默认编码是 GBK（代码页 936），而 Claude Code 输出的是 UTF-8，两边对不上就乱码了。
解决方法分两层：
临时解决（当前窗口有效）：
chcp 65001 $OutputEncoding = [System.Text.Encoding]::UTF8 [Console]::OutputEncoding = [System.Text.Encoding]::UTF8永久解决（推荐）：把这几行写进 PowerShell 的 profile 文件。先敲$PROFILE看路径，然后用编辑器打开那个文件，把上面的命令加进去。这样每次开 PowerShell 自动生效。
但还有个更隐蔽的坑：Windows Terminal 和传统 PowerShell 窗口的编码行为不一样。如果你用的是 Windows Terminal（推荐），它默认就是 UTF-8，基本不会乱码；如果你用的是老式的 PowerShell 窗口，那必须手动设。另外，VS Code 内置终端也要单独设，在 settings.json 里加：
"terminal.integrated.defaultProfile.windows": "PowerShell", "terminal.integrated.env.windows": { "PYTHONIOENCODING": "utf-8" }提示：如果改了 profile 还是乱码，检查一下是不是用了
powershell.exe而不是pwsh.exe。后者是 PowerShell 7，编码处理比 Windows 自带的 5.1 好很多，强烈建议装一个。
3.4 首次运行与 API 配置
装好后第一次敲claude，它会引导你做认证。这里有两种方式：一是用 Anthropic 账号登录（会打开浏览器），二是配置 API Key。如果你在公司网络或者有代理需求，浏览器登录可能会卡，那就用 API Key 方式。
配置 API Key 有两种途径：一是设环境变量ANTHROPIC_API_KEY，二是让 Claude Code 自己存。我建议用环境变量，因为这样切换项目、切换账号都方便。在 PowerShell 里：
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', '你的key', 'User')设完重开终端生效。验证方法是敲claude然后随便问一句，能正常回复就说明通了。
4. WSL2 方案：更接近生产环境的玩法
4.1 把 WSL2 装到 D 盘
默认情况下，wsl --install会把子系统装到 C 盘，虚拟磁盘文件（ext4.vhdx）会随着你装东西越来越大，C 盘很快就红了。所以第一步就是把它挪到 D 盘。
流程是这样的：
- 先正常装 WSL2：管理员 PowerShell 里敲
wsl --install，重启。 - 装完后先别急着用，把默认发行版导出：
wsl --export Ubuntu D:\wsl\ubuntu.tar。 - 注销原来的：
wsl --unregister Ubuntu。 - 导入到 D 盘：
wsl --import Ubuntu D:\wsl\Ubuntu D:\wsl\ubuntu.tar --version 2。 - 设默认用户：
ubuntu config --default-user 你的用户名（这一步容易忘，忘了的话进去是 root）。
这套操作下来，你的 WSL 就完全在 D 盘了，C 盘只留一个几 MB 的启动器。实测下来，导入导出一次大概几分钟，取决于你装了多少东西。
4.2 WSL 内的环境配置
进了 WSL 之后，环境就跟 Ubuntu 服务器一样了。装 Node 建议用 nvm（Linux 版）：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20然后装 Claude Code：
npm install -g @anthropic-ai/claude-codeWSL 里基本不会遇到编码问题，因为 Linux 默认就是 UTF-8。但有个坑要注意：WSL 里的 npm 全局包路径和 Windows 侧是隔离的，你在 WSL 里装的 claude，在 Windows PowerShell 里敲是找不到的，反之亦然。所以别两边混着用，认准一套。
4.3 VS Code 远程连接的正确姿势
WSL2 方案最爽的用法是配 VS Code 的 Remote-WSL。装好WSL扩展后，在 WSL 终端里敲code .，VS Code 就会以远程模式打开当前目录。这时候 VS Code 的终端是 WSL 的 shell，Claude Code 在里面跑，文件读写都在 WSL 内部，性能拉满。
这里有个经验：项目一定要放在 WSL 内部路径（比如~/projects/xxx），别放在/mnt/c/...。我实测过，同样一个前端项目，在/mnt/c下跑npm install要 3 分钟，在~/projects下只要 40 秒，差距就是这么夸张。原因是跨文件系统的 IO 走的是 9P 协议，性能损耗极大。
5. 避坑优化：那些文档不会告诉你的细节
5.1 常见报错速查表
我把这些年遇到的报错整理成表，遇到问题先查这个：
| 报错信息 | 根本原因 | 解决方法 |
|---|---|---|
claude : 无法将"claude"项识别 | PATH 没配好 | 检查 nvm symlink 目录是否在 PATH |
| 中文显示为乱码 | PowerShell 编码非 UTF-8 | chcp 65001+ 设 OutputEncoding |
EACCES/EPERM | 全局包权限不足 | 用 nvm 管理 Node，别用系统 Node |
npm install卡住 | 源太慢 | 切国内镜像--registry |
WSL 里code .没反应 | 没装 WSL 扩展 | VS Code 装WSL扩展 |
nvm use报 Access denied | symlink 目录被占用 | 删C:\Program Files\nodejs，管理员重开 |
| Claude Code 执行命令超时 | 网络或代理问题 | 检查网络，必要时配代理环境变量 |
| 文件路径报错 | Windows 反斜杠 | 用正斜杠或双反斜杠 |
5.2 性能优化的几个关键点
第一，别把 node_modules 放在跨文件系统路径。前面说过，/mnt/c下的 IO 慢得离谱。如果你非要用 Windows 侧的文件，至少把node_modules通过符号链接指到 WSL 内部。
第二，给 WSL 分配合理的内存。默认 WSL2 会吃掉你一半的物理内存，如果你机器内存不大，可以在C:\Users\你的用户名\.wslconfig里限制：
[wsl2] memory=8GB processors=4 swap=2GB改完wsl --shutdown重启生效。这个配置对同时开 Docker 的场景特别有用。
第三，PowerShell 启动慢的话，精简 profile。有些人 profile 里塞了一堆东西，每次开终端要等好几秒。把不常用的初始化逻辑挪到函数里，按需调用。
5.3 我的实操心得
说几个只有实际用过才知道的点：
关于 API Key 的安全。别把 key 硬编码在脚本里，也别提交到 Git。用环境变量是最稳的，如果团队协作，考虑用密钥管理工具。我见过有人把 key 写进.bashrc然后推到公开仓库，第二天就被刷爆了额度。
关于 Claude Code 的权限。它默认会问你"是否允许执行这个命令"，这是安全机制，别嫌烦就全开--dangerously-skip-permissions。我一般只在完全可控的沙箱环境里才用那个参数，日常开发还是手动确认，尤其是涉及删除、覆盖的操作。
关于版本升级。Claude Code 更新很频繁，npm update -g @anthropic-ai/claude-code就能升。但升级后偶尔会有 breaking change，建议升之前看一眼 release notes。我有次升级后配置文件格式变了，折腾了半小时才找到原因。
关于多项目切换。如果你同时维护多个项目，每个项目的 Claude Code 配置可能不一样。可以在项目根目录放一个.claude目录存项目级配置，这样切项目时行为自动跟着变。
6. 进阶玩法：让 Claude Code 真正融入工作流
6.1 和 Git 配合的正确姿势
Claude Code 能直接跑 git 命令，但别让它随便 commit。我的习惯是：让它改代码、跑测试，但 commit 之前我自己 review 一遍。可以给它一个约定："改完代码后跑测试，测试通过后告诉我改了哪些文件，不要自动 commit"。这样既享受了自动化，又保留了控制权。
如果项目有 pre-commit hook，Claude Code 跑 commit 时可能会卡在 hook 上。这时候要么让它用--no-verify（不推荐），要么先把 hook 的问题解决掉。
6.2 自定义命令和快捷方式
Claude Code 支持自定义 slash 命令，你可以在.claude/commands目录下放 markdown 文件，每个文件就是一个命令。比如建一个fix-lint.md，内容写"跑 ESLint，修复所有能自动修的问题，剩下的列出来"，以后敲/fix-lint就能触发。这个功能对重复性任务特别有用，相当于把你的常用 prompt 固化下来。
6.3 在 VS Code 里的集成
除了终端里跑，Claude Code 也有 VS Code 扩展。装完后可以在编辑器里直接调用，选中代码让它改，比切到终端方便。但扩展版和 CLI 版功能不完全一致，复杂任务还是 CLI 更灵活。我的用法是：小改动用扩展，大重构用 CLI。
7. 关于稳定性和长期维护的几点体会
用了大半年 Claude Code，最大的感受是：环境配置的一次性投入，换来的是长期的效率提升。前期花两小时把 Node、PowerShell、WSL 这些理顺，后面基本不会再被环境问题打断。
几个长期维护的建议：一是把环境配置脚本化，换机器时一键恢复；二是定期清理 WSL 的虚拟磁盘，wsl --shutdown后用diskpart压缩，能省不少空间；三是关注 Node 和 Claude Code 的版本兼容性，别盲目追新。
最后分享一个小技巧：如果你在 PowerShell 里经常遇到命令被终止、返回System.Management.Automation.Utils之类的错误，多半是执行策略（ExecutionPolicy）的问题。用Get-ExecutionPolicy看一下，如果是Restricted，改成RemoteSigned：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这个改动只影响当前用户，相对安全，能解决大部分脚本执行被拦的问题。改完记得重开终端。
这套流程我在三台不同配置的 Windows 机器上都跑通过，从 8GB 内存的老笔记本到 32GB 的工作站，核心步骤一致，差异只在性能调优的参数上。照着走一遍，基本能避开我踩过的所有坑。
