1. 为什么要在 Windows 上折腾 Claude Code如果你平时写代码的主力环境是 Windows又眼馋 Claude Code 那种“在终端里直接对话改代码”的体验那这篇内容就是写给你的。Claude Code 本质上是 Anthropic 推出的一个命令行 AI 编程助手它跑在终端里能读你本地的项目文件、执行命令、改代码、跑测试交互方式跟传统的 IDE 插件完全不一样。很多人第一次听说它是在 Mac 或者 Linux 的教程里一到 Windows 就卡在安装环节要么是 PowerShell 执行策略拦住了脚本要么是 Git 和 Node 的环境变量没配好要么是终端编码乱码导致中文路径直接报错。我自己在 Windows 10 和 Windows 11 上都完整走过一遍安装流程也帮身边几个做后端和前端的朋友远程处理过安装失败的问题。踩过的坑包括但不限于npm全局安装后命令找不到、PowerShell 脚本被 Execution Policy 拒绝、Git Bash 和 PowerShell 混用导致路径解析异常、以及终端里中文显示成方块。这些问题单独看都不复杂但凑在一起就很容易让人放弃。这篇内容会从零开始把 Windows 上安装 Claude Code 的完整链路拆开讲清楚前置依赖怎么装、Git 和 Node 的环境变量怎么配、PowerShell 需要做哪些调整、安装命令具体怎么执行、装完之后怎么验证、以及遇到常见报错怎么排查。适合完全没有命令行经验的小白也适合已经装过但没跑起来、想搞清楚问题出在哪的开发者。核心关键词会围绕 Windows、Claude Code、Git、PowerShell、PATH 这几个点展开每一步都会说明为什么这么做而不是只给一串命令让你照抄。2. 安装前的整体思路与依赖选型2.1 为什么 Claude Code 在 Windows 上需要额外准备Claude Code 官方主推的运行环境是 macOS 和 Linux因为它的底层依赖大量 Unix 风格的命令行工具和脚本执行方式。Windows 虽然也有 PowerShell 和 CMD但默认的脚本执行策略、路径分隔符、环境变量管理方式都和 Unix 系不一样。所以你在 Windows 上装 Claude Code本质上是在做一层“环境适配”让 Windows 具备运行 Node 生态命令行工具的基础条件同时让终端能正确执行安装脚本。这里涉及三个核心依赖Node.js 运行时、Git 版本控制工具、PowerShell 终端环境。Node.js 是 Claude Code 的运行基础因为它是通过 npm 包分发的Git 不只是用来管代码Claude Code 内部很多操作依赖 Git 命令来读取项目状态和差异PowerShell 则是你在 Windows 上执行安装命令和日常使用 Claude Code 的主要终端。三者缺一不可而且版本不能太旧。2.2 依赖版本选择与下载渠道Node.js 建议直接上LTS 版本截至我写这篇内容时Node 20.x 和 22.x 的 LTS 都很稳。不要用太老的 16.x部分 npm 包已经不再兼容。下载渠道优先选 Node.js 官网的 Windows Installer安装时记得勾选“Add to PATH”这一步非常关键后面会详细说。Git for Windows 建议下载 64 位 Standalone Installer安装过程中有一堆选项默认配置基本够用但有几个地方需要留意默认编辑器可以选 VS Code 或者 Vim看你习惯PATH 环境那一页建议选“Git from the command line and also from 3rd-party software”这样 PowerShell 和 CMD 里都能直接用git命令。PowerShell 方面Windows 10 和 11 自带的是 Windows PowerShell 5.1功能上够用但如果你想要更好的体验可以装 PowerShell 7.x。不过 Claude Code 在 5.1 上也能跑所以不是必须升级。关键是执行策略要调整否则安装脚本会被直接拦下来。依赖项推荐版本下载方式是否必须Node.js20.x LTS 或 22.x LTS官网 Windows Installer必须Git for Windows2.40 以上官网 64 位安装包必须PowerShell5.1 或 7.x系统自带或 GitHub 下载必须Windows Terminal最新版Microsoft Store推荐2.3 安装顺序为什么不能乱很多人装失败就是因为顺序错了。正确的顺序是先装 Git再装 Node.js最后调 PowerShell。为什么因为 Node.js 安装程序在某些情况下会依赖系统里已有的 Git 来配置 npm 的默认行为虽然这不是强依赖但先装 Git 能避免一些奇怪的路径问题。另外Node.js 安装时会往 PATH 里写东西如果你先调了 PowerShell 的执行策略后面装 Node 又改了环境变量终端会话不重启的话读到的还是旧 PATH就会导致node或npm命令找不到。所以我的建议是三个东西全部装完、环境变量全部配好之后关掉所有终端窗口重新开一个 PowerShell再开始验证和安装 Claude Code。这个细节看起来很小但能省掉你至少半小时的排查时间。3. Git 与 Node 环境配置实操3.1 Git 安装时的关键选项Git for Windows 的安装向导大概有十几步大部分可以默认但有几个地方必须注意。第一处是“Adjusting your PATH environment”这里一定要选第二项“Git from the command line and also from 3rd-party software”。选第一项的话Git 命令只能在 Git Bash 里用PowerShell 里调不到选第三项会覆盖 Windows 自带的 find 和 sort 工具容易出问题。第二处是“Choosing the SSH executable”默认用 OpenSSH 就行不用换成 PuTTY。第三处是“Configuring the line ending conversions”建议选“Checkout Windows-style, commit Unix-style line endings”这样跨平台协作时不会因为换行符问题产生大量无意义的 diff。第四处是“Choosing a credential helper”选“Git Credential Manager”或者“None”都可以看你是否需要用 HTTPS 方式拉取私有仓库。装完之后打开一个新的 PowerShell输入git --version如果能看到类似git version 2.43.0.windows.1的输出说明 Git 已经正确进入 PATH。如果提示“无法将‘git’项识别为 cmdlet”那就是 PATH 没配好需要手动加。3.2 Node.js 安装与 npm 环境变量Node.js 的 Windows Installer 安装过程比较简单一路 Next 就行但务必确认“Add to PATH”这个选项是勾上的。装完之后同样要开新终端验证node -v npm -v正常的话会分别输出 Node 和 npm 的版本号。如果node能用但npm不能用或者反过来那说明 PATH 里只加了一部分。Node.js 安装程序通常会把 Node 和 npm 的可执行文件放在同一个目录下比如C:\Program Files\nodejs\这个目录应该被加到系统 PATH 里。有时候你会遇到 npm 全局安装的包命令找不到的情况这是因为 npm 的全局包目录没有加到 PATH。你可以用下面命令查看 npm 的全局路径npm config get prefix默认情况下Windows 上这个路径是C:\Users\你的用户名\AppData\Roaming\npm。你需要把这个路径手动加到系统环境变量 PATH 里。具体操作是右键“此电脑” → 属性 → 高级系统设置 → 环境变量 → 在“用户变量”里找到 Path → 编辑 → 新建 → 把 npm 全局路径粘贴进去 → 确定。加完之后一定要重开终端才生效。提示修改 PATH 之后已经打开的 PowerShell 窗口不会自动刷新环境变量。你可以用$env:Path查看当前会话的 PATH确认新路径是否已经包含在内。如果没有关掉重开。3.3 PowerShell 执行策略调整PowerShell 默认的执行策略是 Restricted意思是任何脚本都不让跑。Claude Code 的安装脚本和一些 npm 生命周期脚本需要执行权限所以你要把执行策略改成 RemoteSigned。这个策略的意思是本地写的脚本可以直接跑从网络下载的脚本需要有数字签名才能跑。对于开发环境来说这是一个比较平衡的安全设置。打开 PowerShell以管理员身份运行然后执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser系统会提示你确认输入 Y 回车即可。-Scope CurrentUser表示只对当前用户生效不需要改全局策略更安全。改完之后可以用下面命令验证Get-ExecutionPolicy -Scope CurrentUser如果输出RemoteSigned说明设置成功。这里要注意如果你在公司电脑上组策略可能锁定了执行策略这种情况下你改不了需要联系 IT 管理员。个人电脑一般没这个问题。另外有些安装脚本会用到-ep bypass参数来临时绕过执行策略比如powershell -ep bypass -c ...这种写法。这只是临时绕过不会永久修改系统设置但你在执行任何这类命令之前一定要确认脚本来源可信。不要随便在网上复制一条命令就往 PowerShell 里粘贴尤其是涉及网络下载和执行的。4. Claude Code 安装与验证全流程4.1 通过 npm 安装 Claude Code前置依赖全部就绪之后安装 Claude Code 本身其实就一条命令npm install -g anthropic-ai/claude-code-g表示全局安装这样你在任何目录下都能直接用claude命令。安装过程中 npm 会从 registry 拉取包如果你的网络环境访问 npm 官方源比较慢可以临时切换到国内镜像源npm config set registry https://registry.npmmirror.com装完之后可以切回来npm config set registry https://registry.npmjs.org安装完成后验证命令是否可用claude --version如果输出了版本号说明安装成功。如果提示“无法将‘claude’项识别为 cmdlet”大概率是 npm 全局路径没加到 PATH回到 3.2 节检查。4.2 首次启动与配置第一次运行claude命令时它会引导你完成一些初始配置比如选择主题、确认一些使用条款、以及配置 API 相关的信息。具体配置内容根据你的使用方式不同会有差异这里不展开。你需要确保的是终端能正常显示交互界面键盘输入能被正确识别。如果你在 PowerShell 里遇到界面显示错乱、光标位置不对、或者中文变成乱码通常是终端编码问题。可以尝试设置 PowerShell 的编码为 UTF-8[Console]::OutputEncoding [System.Text.Encoding]::UTF8 $OutputEncoding [System.Text.Encoding]::UTF8这两条命令只对当前会话生效。如果你想永久生效可以把它们加到 PowerShell 的 profile 文件里。查看 profile 路径$PROFILE如果文件不存在可以手动创建然后把上面两行写进去。这样每次开 PowerShell 都会自动设置 UTF-8 编码。4.3 在项目目录中使用 Claude CodeClaude Code 的使用方式很简单cd到你的项目目录然后直接运行claude。它会自动读取当前目录下的文件结构和 Git 状态然后你就可以用自然语言让它帮你改代码、查 bug、写测试。cd D:\projects\my-app claude进入交互界面后你可以输入类似“帮我看看这个函数为什么报错”、“给这个模块加单元测试”、“把这段代码重构成 async/await”这样的指令。Claude Code 会读取相关文件给出修改建议并在你确认后直接写入文件。这里有一个实操心得确保你的项目目录是一个 Git 仓库。Claude Code 很多功能依赖 Git 来追踪文件变化如果目录不是 Git 仓库部分能力会受限。你可以在项目根目录执行git init来初始化。git init git add . git commit -m initial commit这样做还有一个好处Claude Code 改完代码后你可以用git diff清楚地看到它改了哪些地方方便 review 和回滚。5. 常见报错与排查技巧实录5.1 命令找不到类问题这是最常见的一类问题表现是输入node、npm、git或claude之后PowerShell 提示“无法将xxx项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。根本原因只有一个对应的可执行文件所在目录没有出现在当前会话的 PATH 环境变量里。排查步骤很简单。先用下面命令查看当前 PATH$env:Path -split ;然后确认 Node、npm、Git 的安装路径是否在列表里。如果没有就手动加。加完之后必须重开终端。如果加了还是不行检查路径是否写错比如多了空格、用了中文引号、或者路径根本不存在。还有一种情况是你装了多个版本的 NodePATH 里旧版本的路径排在前面导致node -v显示的是旧版本。这时候要么卸载旧版本要么调整 PATH 顺序把新版本路径移到前面。5.2 执行策略与脚本被拦截如果你在安装或运行过程中看到类似“无法加载文件因为在此系统上禁止运行脚本”的报错那就是执行策略的问题。回到 3.3 节用Set-ExecutionPolicy改成 RemoteSigned。如果改不了检查是不是被组策略限制。另外有些 npm 包在安装时会执行 postinstall 脚本如果执行策略太严格这些脚本会失败导致包安装不完整。表现是安装过程没有明显报错但命令就是不能用。这种情况下重新设置执行策略后删掉 node_modules 和 package-lock.json 重新安装。5.3 终端编码与中文乱码Windows PowerShell 5.1 默认编码是 GBK而很多现代命令行工具输出的是 UTF-8两者不一致就会导致中文乱码。表现是终端里中文显示成问号、方块或者乱码字符。解决办法就是 4.2 节提到的设置 UTF-8 编码或者升级到 PowerShell 7.x后者默认就是 UTF-8。如果你在 Claude Code 交互界面里看到乱码除了编码设置还要检查 Windows Terminal 的字体设置。有些等宽字体不包含中文字形中文会显示成方块。换一个支持中文的等宽字体比如“Cascadia Code”配合“微软雅黑”回退或者直接用“Sarasa Mono SC”这类专门为中文优化的等宽字体。问题现象可能原因解决方法命令找不到PATH 未包含安装目录手动添加 PATH 并重开终端脚本被禁止运行执行策略为 Restricted改为 RemoteSigned中文显示乱码终端编码非 UTF-8设置 UTF-8 或升级 PowerShellnpm 安装慢默认源访问慢临时切换国内镜像源全局包命令找不到npm 全局路径未加 PATH添加npm config get prefix路径5.4 网络与代理相关注意事项npm 安装包时如果网络不稳定可能会出现超时或者部分文件下载失败。表现是安装过程卡住很久最后报错退出。这种情况下可以多试几次或者切换镜像源。如果你所在网络环境有特殊的代理设置需要确保 npm 的代理配置和系统代理一致。可以用下面命令查看和设置npm config get proxy npm config get https-proxy npm config set proxy http://你的代理地址:端口 npm config set https-proxy http://你的代理地址:端口不需要代理的时候记得删掉否则会影响正常访问npm config delete proxy npm config delete https-proxy注意任何涉及网络下载和执行脚本的操作都要确认来源可信。不要随意执行来源不明的 PowerShell 脚本尤其是那种一行命令直接从网络下载并执行的写法。6. 提升使用体验的几个配置6.1 配置 PowerShell 开机自启脚本如果你希望每次打开 PowerShell 都自动设置好编码、PATH 补充、别名等可以把这些配置写进 profile 文件。前面说过用$PROFILE查看路径然后编辑这个文件。一个比较实用的 profile 模板大概长这样# 设置 UTF-8 编码 [Console]::OutputEncoding [System.Text.Encoding]::UTF8 $OutputEncoding [System.Text.Encoding]::UTF8 # 添加 npm 全局路径如果还没加的话 $npmPath $env:APPDATA\npm if ($env:Path -notlike *$npmPath*) { $env:Path ;$npmPath } # 常用别名 Set-Alias ll Get-ChildItem Set-Alias g git这样每次开终端都会自动生效不用手动敲一遍。注意 profile 文件里的路径要根据你自己的实际安装位置调整。6.2 在 VS Code 中集成 Claude Code如果你平时用 VS Code 写代码可以直接在 VS Code 的集成终端里运行 Claude Code。打开 VS Code按Ctrl调出终端默认就是 PowerShell。然后cd到项目目录运行claude即可。这样你一边看代码一边和 Claude Code 对话改完直接在当前窗口 review效率比来回切窗口高很多。如果 VS Code 终端里中文乱码检查 VS Code 的终端编码设置。在 settings.json 里加上{ terminal.integrated.defaultProfile.windows: PowerShell, terminal.integrated.fontFamily: Cascadia Code, Sarasa Mono SC }字体列表里加上支持中文的等宽字体能解决大部分显示问题。6.3 日常使用中的几个小技巧第一养成先 commit 再让 Claude Code 改代码的习惯。这样改坏了可以直接git checkout .回滚不用担心代码丢失。第二用.claudeignore文件排除不需要 AI 读取的目录比如 node_modules、dist、.git 等能加快响应速度也避免无关文件干扰。第三在项目根目录放一个 CLAUDE.md 文件写上项目的基本信息、技术栈、代码规范Claude Code 启动时会自动读取给出的建议会更贴合你的项目。第四如果你同时用多个 AI 编程工具注意它们之间的配置不要互相覆盖。比如有的工具会改 npm 全局配置有的会改 Git 配置装多了容易乱。建议每装一个新工具后用npm config list和git config --list检查一下当前配置确认没有异常改动。7. 我个人在实际操作中的几点体会Windows 上装 Claude Code 这件事说难不难说简单也不简单。核心难点不在 Claude Code 本身而在于 Windows 的命令行生态和 Unix 系差异太大导致很多在 Mac 上一条命令搞定的事情在 Windows 上需要多绕几步。但只要你把 Git、Node、PowerShell 这三个基础打牢后面装任何 Node 生态的命令行工具都会顺很多。我自己的习惯是每台新电脑到手先按“Git → Node → PowerShell 执行策略 → PATH 检查”这个顺序走一遍把基础环境一次性配好。后面不管装什么工具基本都是一条npm install -g的事。另外遇到报错不要慌先看错误信息里的关键词大部分问题都能归结到 PATH、权限、编码这三类。把这三类问题的排查方法记熟能解决九成以上的安装问题。最后分享一个我踩过的坑有一次帮朋友装所有步骤都对了但claude命令就是找不到。排查了半天发现他之前装过一个旧版本的 NodePATH 里旧路径排在前面npm 全局包装到了旧版本的目录下新版本的 PATH 里自然找不到。所以如果你电脑上装过多个版本的 Node一定要确认当前用的是哪个版本以及 npm 全局包到底装到了哪里。用where.exe node和where.exe npm可以查看实际调用的可执行文件路径这个命令在排查 PATH 问题时非常有用。
