1. 为什么要在 Windows 上折腾 Claude CodeClaude Code 刚出来那阵子官方主推的是 macOS 和 Linux 环境Windows 用户基本处于“二等公民”状态。但现实情况是国内大量开发者的主力工作机就是 Windows尤其是做后端、数据、运维方向的朋友公司配的开发本清一色 Windows。你不可能为了用一个命令行 AI 编程工具就专门换台 Mac所以把 Claude Code 在 Windows 上跑通是一个很实际的需求。Claude Code 本质上是一个跑在终端里的 AI 编程助手它能直接读写你本地的项目文件、执行命令、跑测试、改代码。跟那种在网页里复制粘贴代码的体验完全不是一个量级——它更像是一个坐在你旁边、能直接操作你键盘的结对程序员。而 Windows 上要让它跑起来核心依赖三样东西Node.js 运行环境、Git 版本控制工具、以及一个能正常工作的 PowerShell 终端。这三样缺一不可而且每一个都有坑。这篇内容适合什么人看如果你是 Windows 用户听说过 Claude Code 但一直没装成功或者装完了发现命令找不到、终端乱码、权限报错那这篇就是写给你的。我会从零开始把每一步的命令、每一个参数为什么这么写、以及我实际踩过的坑全部摊开讲清楚。不需要你有多深的命令行基础但需要你愿意动手敲几条命令。整个流程走下来顺利的话二十分钟以内能搞定。不顺利的话大概率是卡在 PATH 环境变量或者 PowerShell 执行策略上这两个问题我在后面会重点拆解。2. 安装前的环境盘点与工具选型2.1 三件套的版本要求与下载渠道在动手之前先把需要的东西列清楚。Claude Code 官方对运行环境有明确要求我整理成表格方便对照组件最低版本要求推荐版本作用Node.js18.x20.x LTS提供 npm 包管理器和 JS 运行时Git for Windows2.40最新版提供 git 命令和 Git Bash 环境PowerShell5.17.x终端宿主环境Windows10 180911操作系统底座Node.js 去官网下 LTS 版本就行安装包直接双击下一步。这里有个细节安装时记得勾选“Add to PATH”那个选项默认是勾上的但有些人手快取消了后面就得手动配环境变量非常麻烦。Git for Windows 同样官网下载安装过程中会问你默认编辑器选什么、PATH 环境怎么配。PATH 那一页建议选“Git from the command line and also from 3rd-party software”也就是中间那个选项。这样 git 命令在 PowerShell 和 CMD 里都能直接用。如果你选了第一项“Use Git from Git Bash only”那 PowerShell 里敲 git 会提示找不到命令后面 Claude Code 调用 git 就会失败。PowerShell 这块Windows 10 和 11 自带的 5.1 版本其实够用但如果你想体验更好可以装 PowerShell 7。5.1 和 7 可以共存不冲突。我个人的建议是先用自带的 5.1 把流程跑通跑通之后再考虑升级。2.2 为什么 Claude Code 对 Windows 这么挑剔这里得解释一下 Claude Code 的底层逻辑。它本身是一个 npm 包通过 Node.js 运行。但它在工作过程中会频繁调用系统命令比如git status、ls、cat这些。在 macOS 和 Linux 上这些命令天然存在终端环境也统一。但 Windows 上命令行的生态是分裂的——CMD、PowerShell、Git Bash 各有一套语法路径分隔符是反斜杠换行符也不一样。Claude Code 为了跨平台内部做了不少兼容处理但它仍然依赖一个“类 Unix”的命令执行环境。这就是为什么 Git for Windows 是必须的——它不只是提供 git 命令还附带了一套 Git Bash 工具链Claude Code 在 Windows 上会借用这套工具来执行很多操作。所以如果你只装了 Node.js 没装 GitClaude Code 能启动但一执行文件操作就可能报错。另一个关键点是PATH 环境变量。Windows 查找可执行文件的逻辑是遍历 PATH 里的目录找到第一个匹配的就执行。如果 Node.js 和 Git 的安装路径没进 PATH或者进了但顺序不对就会出现“命令找不到”或者“调用了错误版本”的问题。这个在后面配置环节会详细说。2.3 安装顺序与前置检查安装顺序建议是先 Git再 Node.js最后 Claude Code。原因是 Node.js 安装过程中会检测系统里有没有 Git如果有它会自动配置一些关联设置。反过来先装 Node.js 再装 Git虽然也能用但少了一层自动配置的便利。装之前先做个检查打开 PowerShellWin X 然后按 A或者开始菜单搜 PowerShell敲下面两条命令node -v git --version如果两条都返回版本号说明你之前已经装过了可以跳过安装直接看配置部分。如果提示“无法将‘node’项识别为 cmdlet”那就是没装或者没进 PATH。注意刚装完 Node.js 后必须重新开一个 PowerShell 窗口旧窗口的环境变量不会自动刷新这是新手最容易懵的地方。3. 手把手完成核心安装与配置3.1 Git 安装的隐藏选项与 PATH 配置Git 安装包双击后前面几步都是常规的下一步到“Adjusting your PATH environment”这一页要停一下。三个选项分别是Use Git from Git Bash only最保守只有 Git Bash 里能用 gitGit from the command line and also from 3rd-party software推荐PowerShell 和 CMD 都能用Use Git and optional Unix tools from the Command Prompt会把 Unix 工具也加进 PATH可能和系统自带命令冲突选中间那个。继续往下到“Choosing the default editor used by Git”这页默认是 Vim如果你不熟悉 Vim 的操作建议改成 Nano 或者你熟悉的编辑器。这个设置影响的是 git commit 时弹出的编辑器跟 Claude Code 关系不大但改了能省心。再往后有个“Configuring the line ending conversions”三个选项Checkout Windows-style, commit Unix-style line endings推荐Checkout as-is, commit Unix-style line endingsCheckout as-is, commit as-is选第一个。这个设置决定了 Git 怎么处理换行符。Windows 用 CRLFUnix 用 LF如果处理不好代码在跨平台协作时会出现整个文件都显示被修改的情况。选第一个能让 Git 自动转换省去很多麻烦。装完之后验证一下git --version返回类似git version 2.43.0.windows.1就对了。然后配置一下全局用户名和邮箱这是 git commit 时必须的git config --global user.name 你的名字 git config --global user.email 你的邮箱example.com这两条命令写入的是全局配置存在C:\Users\你的用户名\.gitconfig文件里。Claude Code 在执行 git 操作时会读取这个配置如果不配某些操作会报错。3.2 Node.js 安装与 npm 环境变量 PATH 配置Node.js 安装相对简单官网下载 LTS 版双击一路下一步。安装完成后务必新开一个 PowerShell 窗口然后验证node -v npm -v两条都返回版本号才算成功。如果 node 有版本号但 npm 报错大概率是 npm 的全局路径没配好。这时候需要检查 npm 的全局安装目录是否在 PATH 里。执行npm config get prefix返回的路径就是 npm 全局包的安装位置通常是C:\Users\你的用户名\AppData\Roaming\npm。这个路径必须出现在系统 PATH 环境变量里否则你全局安装的命令行工具都无法直接调用。手动添加 PATH 的步骤Win S 搜“环境变量”打开“编辑系统环境变量”点“环境变量”按钮在“用户变量”区域找到 Path双击新建一条把上面那个路径粘贴进去。确定保存后重新开 PowerShell 窗口再验证。这里有个坑要提醒有些人 PATH 里同时存在多个 node 路径比如之前装过 nvm 或者手动解压过 node导致node -v返回的版本和预期不一致。排查方法是where.exe node这条命令会列出所有匹配的 node 路径按顺序执行。如果第一个不是你想要的就去 PATH 里调整顺序把正确的路径移到前面。3.3 Claude Code 安装与 PowerShell 执行策略调整环境准备好之后安装 Claude Code 本身反而最简单npm install -g anthropic-ai/claude-code等它跑完验证claude --version如果返回版本号恭喜你主体安装完成。但接下来大概率会遇到 PowerShell 的执行策略问题。Windows 默认的 PowerShell 执行策略是 Restricted不允许运行任何脚本。Claude Code 在运行过程中会生成和执行一些临时脚本被策略拦住就会报错典型错误信息是“无法加载文件因为在此系统上禁止运行脚本”。解决办法是调整执行策略。以管理员身份打开 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这条命令的意思是对当前用户允许运行本地创建的脚本从网络下载的脚本需要签名。-Scope CurrentUser限定只影响当前用户不需要管理员权限也能生效比改全局策略更安全。执行后会问你是否确认输入 Y 回车。验证策略是否生效Get-ExecutionPolicy -Scope CurrentUser返回 RemoteSigned 就对了。注意不要图省事直接设成 Unrestricted那等于对所有脚本放行安全性会打折扣。RemoteSigned 是微软官方推荐的开发环境策略平衡了便利和安全。3.4 首次启动与 API 配置安装完成后在项目目录下敲claude就能启动。首次启动会引导你配置 API 密钥或者登录账号。如果你用的是官方服务按提示走浏览器授权流程即可。如果你用的是兼容接口需要设置环境变量$env:ANTHROPIC_API_KEY你的密钥 $env:ANTHROPIC_BASE_URL你的接口地址这种设置方式只在当前 PowerShell 窗口有效关掉就没了。要永久生效得写进用户环境变量或者写进 PowerShell 的 profile 文件。profile 文件的位置可以用$PROFILE查看通常是在C:\Users\你的用户名\Documents\PowerShell\Microsoft.PowerShell_profile.ps1。把上面两行加进去每次开 PowerShell 就自动加载。不过要注意把密钥明文写在 profile 文件里有一定安全风险如果这台机器多人使用建议还是每次手动设置或者用更安全的凭据管理方式。4. 实操验证与典型场景跑通4.1 在真实项目里跑一次完整流程装完不验证等于没装。找一个你现有的项目目录或者新建一个测试目录在里面启动 Claude Codecd D:\projects\test-demo claude启动后你会看到一个交互式界面。先试一个最简单的指令比如输入“看一下当前目录有哪些文件”它应该能正确列出目录内容。这一步验证的是文件读取能力。再试一个涉及 git 的操作输入“查看当前的 git 状态”。如果项目已经初始化了 git 仓库它应该能返回分支信息和修改状态。这一步验证的是 git 集成。最后试一个写操作输入“创建一个 hello.txt 文件内容写 Hello Claude”。执行完后用ls或者文件管理器确认文件确实生成了。这一步验证的是文件写入权限。三步都通过说明安装配置完全没问题。如果某一步失败对照下面的排查表处理。4.2 常见报错与排查速查表报错信息根本原因解决方法claude 不是内部或外部命令npm 全局路径不在 PATH把 npm prefix 路径加入 PATH无法加载文件禁止运行脚本PowerShell 执行策略限制Set-ExecutionPolicy RemoteSignedgit 不是内部或外部命令Git 未加入 PATH重装 Git 选中间 PATH 选项node 版本过低Node.js 低于 18升级到 20 LTS终端中文乱码编码不是 UTF-8chcp 65001 或改终端设置权限被拒绝目录无写入权限换目录或用管理员运行npm install 卡住网络问题配置镜像源或重试4.3 终端乱码与编码问题处理Windows PowerShell 5.1 默认编码是 GBK而 Claude Code 输出的是 UTF-8两者不一致就会出现中文乱码。临时解决方法是启动前执行chcp 65001这会把当前代码页切到 UTF-8。但每次开窗口都要敲一遍很烦可以写进 profile 文件。更彻底的方案是升级到 PowerShell 7它默认就是 UTF-8而且对现代终端特性的支持更好。如果你用的是 Windows Terminal可以在设置里把对应 profile 的编码固定为 UTF-8。具体路径是设置 - 配置文件 - 你的 PowerShell - 高级 - 编码选 65001。提示乱码问题不影响功能只影响阅读体验。但如果你在 Claude Code 里处理中文文件内容编码不一致可能导致文件读写异常所以还是建议尽早统一成 UTF-8。5. 效率提升与进阶配置5.1 把 Claude Code 集成进 VS Code如果你主力用 VS Code 写代码可以把 Claude Code 集成到内置终端里省得来回切窗口。方法很简单在 VS Code 里按 Ctrl 打开终端直接敲claude 就能用。VS Code 的终端默认就是 PowerShell环境变量继承自系统所以只要系统层面配好了这里直接能用。更进一步可以配置 VS Code 的 tasks.json把 Claude Code 做成一个任务用快捷键唤起。不过我个人觉得没必要内置终端已经够方便了。真正值得做的是把常用项目的启动命令做成 alias比如在 profile 里加function cc { claude args }这样敲cc就等于敲claude少打几个字符。别小看这点效率提升一天下来能省不少事。5.2 项目级配置与权限管理Claude Code 支持项目级配置文件在项目根目录放一个.claude/settings.json可以定义这个项目下的行为比如允许哪些命令、禁止哪些操作。这对于团队协作很有用把配置提交到仓库所有人共享同一套规则。一个典型的配置示例{ permissions: { allow: [Bash(git status), Bash(git diff)], deny: [Bash(rm -rf)] } }这个配置允许执行 git 状态查看和差异对比禁止执行危险的删除命令。权限系统的逻辑是白名单和黑名单结合具体语法可以参考官方文档。我的建议是初期先用默认配置等熟悉了再逐步收紧权限。5.3 开机自启脚本与后台服务思路有些朋友想让 Claude Code 相关的服务开机自启比如一个本地的接口转发服务。Windows 上实现开机自启有几种方式任务计划程序、启动文件夹、注册表 Run 键。最推荐的是任务计划程序因为可以精细控制触发条件和运行权限。创建一个基本任务触发器选“计算机启动时”操作选“启动程序”程序填 powershell.exe参数填-ExecutionPolicy Bypass -File C:\path\to\your-script.ps1。注意这里的-ExecutionPolicy Bypass是针对这个特定脚本临时绕过策略不影响系统全局设置比改全局策略更安全。不过要提醒一句后台常驻服务会占用资源如果不是必需没必要什么都设自启。Claude Code 本身是按需启动的命令行工具不需要常驻。6. 我踩过的坑与实操心得第一个坑是PATH 顺序问题。我机器上之前装过旧版 Node.js后来又装了新版结果 PATH 里旧版路径排在前面node -v一直返回旧版本。排查了半天才发现是顺序问题。用where.exe node一看就清楚了把新路径移到前面解决。这个命令建议大家记住排查命令冲突时特别好用。第二个坑是PowerShell 执行策略的作用域。我一开始用管理员权限改了 LocalMachine 级别的策略结果公司安全软件报警了。后来改成 CurrentUser 级别既解决了问题又不触发安全告警。所以改策略时一定要加-Scope CurrentUser。第三个坑是Git 的换行符配置。有次协作项目我提交的代码在别人机器上整个文件都显示被修改diff 一片红。查了半天是换行符转换配置不一致。统一成core.autocrlftrue之后问题消失。这个配置在 Git 安装时就能设好但很多人装的时候没注意。第四个坑是终端编码。处理一个含中文注释的项目时Claude Code 读出来的中文全是乱码导致它理解错了代码意图。后来把 PowerShell 编码统一成 UTF-8 才正常。所以如果你经常处理中文内容编码这关一定要过。最后一个心得不要在生产环境或者重要仓库里直接让 Claude Code 执行写操作。先在测试目录里跑通流程确认行为符合预期再逐步放开权限。AI 工具再智能也可能误操作做好 git 提交和备份是底线。我现在的习惯是让 Claude Code 改代码之前先git commit一次这样出问题随时能回滚。这套流程我在三台不同配置的 Windows 机器上都跑过从 Win10 到 Win11从 PowerShell 5.1 到 7整体稳定性没问题。核心就是那三样依赖装对、PATH 配对、策略放开剩下的就是熟练度问题。