Claude Code 这两年在开发者圈子里热度一直不低但真正动手在 Windows 上装的时候很多人第一步就卡住了——不是 Node 版本不对就是 PowerShell 执行策略拦着不让跑脚本再不然就是 Git 装完了命令行里死活认不出来。我自己前前后后在三台不同配置的 Windows 机器上折腾过这套环境从 Win10 家庭版到 Win11 专业版都试过踩的坑基本能凑成一本小册子。这篇就把 Windows 下从零搭建 Claude Code 运行环境的完整链路拆开讲清楚包括 Git 的安装与 PATH 配置、PowerShell 的版本确认与执行策略调整、Node.js 环境的准备以及最后 Claude Code 的安装验证。不管你是刚接触命令行的小白还是换了新电脑要重新配环境的老手照着走一遍基本能少走大半弯路。1. 先把环境底座理清楚为什么 Windows 装 Claude Code 容易翻车1.1 Claude Code 到底依赖哪些底层组件很多人以为 Claude Code 就是一个下载下来双击运行的 exe实际上它本质上是一个跑在 Node.js 运行时上的命令行工具通过 npm 全局安装的方式分发。这就意味着你的 Windows 系统里必须先把三样东西准备好Node.js 运行时、npm 包管理器装 Node 时会自带、以及一个能正常执行 npm 命令的终端环境。而 npm 全局安装的包默认会往用户目录下的一个全局目录里写文件这个目录又必须被加到系统的 PATH 环境变量里否则你装完了在命令行敲claude会提示不是内部或外部命令。再往下一层Claude Code 在工作过程中会调用 Git 来做版本控制相关的操作比如查看改动、生成 diff、提交记录等。所以 Git 不是可选项而是事实上的硬依赖。Git 在 Windows 上安装时又会涉及一个经典问题安装程序问你要不要把 Git 加到 PATH很多人一路点下一步给跳过了结果后面 Claude Code 调用 Git 时就报找不到命令。把依赖关系画成一张清单会更直观组件作用是否必须常见翻车点Node.js提供 JS 运行时必须版本过低低于 18 会出问题npm安装 Claude Code必须全局目录未加入 PATHGit版本控制操作必须安装时未勾选加入 PATHPowerShell执行命令的终端必须执行策略限制脚本运行系统 PATH让命令全局可用必须多个工具都依赖它这张表看着简单但每一行背后都有具体的操作细节下面逐个拆。1.2 为什么推荐用 PowerShell 而不是 CMDWindows 上能用的终端有好几个老式的 CMD、PowerShell、Windows Terminal还有 Git 自带的 Git Bash。我实测下来PowerShell 是装 Claude Code 最省心的选择原因有几个。第一npm 在 PowerShell 下的输出更规范不会出现 CMD 里那种中文乱码或者进度条刷屏的问题。第二PowerShell 对管道和脚本的支持更完整后面如果要写一些自动化配置脚本会方便很多。第三Windows 11 默认终端就是 PowerShellWin10 也能直接搜到不用额外装东西。CMD 不是不能用但它在处理一些带空格路径、环境变量展开的时候容易出幺蛾子新手排查起来很痛苦。Git Bash 虽然也能跑 npm但它和 Windows 原生环境的路径映射有时候会对不上尤其是全局安装的包路径。所以我的建议是统一用 PowerShell把 CMD 和 Git Bash 先放一边减少变量。提示如果你用的是 Windows Terminal记得把默认配置文件设成 PowerShell而不是 CMD。在设置里改一下默认配置文件就行省得每次开窗口都要手动切。1.3 装之前先确认系统版本和权限动手之前花两分钟确认两件事。第一你的 Windows 是 64 位还是 32 位这决定了你下载 Node.js 和 Git 时选哪个安装包。在设置 → 系统 → 关于里能看到系统类型。现在基本都是 64 位但老机器上偶尔还能见到 32 位下错了装不上。第二确认你的账户有没有管理员权限。安装 Node.js 和 Git 的时候安装程序会请求管理员权限来写系统目录和注册表。如果你用的是公司电脑账户被限制了权限可能会卡在安装环节。这种情况要么找 IT 要权限要么用便携版portable的 Node.js 解压到用户目录然后手动配 PATH。便携版稍微麻烦点但能绕开权限限制。2. Git 安装与 PATH 配置那个最容易被忽略的勾选项2.1 下载与安装 Git 的正确姿势Git 官方下载地址是 git-scm.com进去之后点 Windows 版本的下载按钮会自动根据你的系统架构推荐合适的安装包。下载下来是个 exe双击开始安装。安装过程有一堆选项页大部分人看到就头大其实真正需要你留意的就那么几个。第一个关键页是Select Components这里默认勾选的东西基本够用不用动。第二个关键页是Adjusting your PATH environment这一页有三个选项Use Git from Git Bash only只允许在 Git Bash 里用 Git不推荐等于白装。Git from the command line and also from 3rd-party software推荐选这个会把 Git 加到系统 PATH让 PowerShell 和 CMD 都能调用。Use Git and optional Unix tools from the Command Prompt会把一些 Unix 工具也加进去可能和系统自带命令冲突不推荐。选中间那个也就是第二项。这是整个安装过程中最重要的一步选错了后面 Claude Code 调用 Git 就会失败。后面的选项页比如换行符处理Checkout Windows-style, commit Unix-style line endings、终端模拟器选择Use MinTTY、凭证管理器Git Credential Manager这些保持默认即可。换行符那个选项对跨平台协作有影响但日常单人开发用默认值不会出问题。2.2 验证 Git 是否真的进了 PATH装完之后别急着往下走先验证一下。关掉所有已经打开的 PowerShell 窗口重新开一个这一步很重要因为 PATH 的变更需要新开的终端才能生效。然后敲git --version如果返回类似git version 2.43.0.windows.1这样的信息说明 Git 装好了而且 PATH 也配对了。如果提示无法将git项识别为 cmdlet、函数、脚本文件或可运行程序的名称那就是 PATH 没配上。这种情况有两个原因一是安装时没选对那个 PATH 选项二是选了但当前终端是旧的。先确认是不是开了新窗口如果新窗口还是不行就得手动加 PATH。2.3 手动补 PATH 的完整操作手动加 PATH 的路径是右键此电脑 → 属性 → 高级系统设置 → 环境变量。在系统变量里找到名为Path的那一项双击打开点新建把 Git 的安装路径加进去。默认安装路径一般是C:\Program Files\Git\cmd注意是cmd这个子目录不是 Git 根目录。这个目录里放着git.exe加对了才能全局调用。加完之后一路点确定然后重新开一个 PowerShell 窗口再试git --version。注意环境变量改完之后已经打开的终端不会自动刷新必须新开窗口。我见过有人改完 PATH 在当前窗口反复试一直不生效白白折腾半小时。2.4 Git 的初始配置别偷懒Git 装好之后建议顺手把用户名和邮箱配了不然 Claude Code 在生成提交信息或者做版本操作时可能会报错。两条命令git config --global user.name 你的名字 git config --global user.email 你的邮箱这两条是全局配置写一次就行。另外可以配一下默认分支名现在主流是maingit config --global init.defaultBranch main这些配置看着和 Claude Code 没直接关系但它们是 Git 能正常工作的前提。Claude Code 在帮你处理代码改动时底层调用的就是这些 Git 配置配好了能省掉后面一堆莫名其妙的报错。3. Node.js 与 npm 环境版本选对全局目录配对3.1 Node.js 版本怎么选Claude Code 对 Node.js 版本有要求太老的版本跑不起来。我建议直接上Node.js 20 LTS或者更高的 LTS 版本。LTS 是长期支持版稳定性有保障不会像最新版那样偶尔冒出兼容性问题。去 nodejs.org 下载 Windows 安装包.msi64 位系统选 x64一路下一步装完就行。安装过程中有一个选项是Automatically install the necessary tools这个会额外装一些编译工具装 Claude Code 用不上可以跳过省时间。安装程序默认会把 Node.js 和 npm 加到 PATH这个不用你操心。装完同样要新开 PowerShell 窗口验证node --version npm --version两条命令都能返回版本号说明 Node 环境就绪了。3.2 npm 全局目录的 PATH 陷阱这是 Windows 上装全局 npm 包最容易踩的坑。npm 全局安装的包可执行文件会被放到一个全局目录里这个目录默认在C:\Users\你的用户名\AppData\Roaming\npm问题在于这个目录不一定自动加到系统 PATH 里。Node.js 安装程序有时候会加有时候不会取决于版本和安装方式。如果没加你npm install -g装完 Claude Code敲claude会提示找不到命令。验证方法很简单先查一下 npm 的全局目录在哪npm config get prefix返回的路径就是全局目录。然后检查这个路径有没有在 PATH 里。在 PowerShell 里敲$env:Path -split ;这会列出当前 PATH 的所有条目你肉眼扫一下有没有上面那个 npm 目录。如果没有就按 2.3 节的方法手动加进去。3.3 用 npm 全局安装 Claude Code环境都就绪之后安装 Claude Code 本身反而最简单。在 PowerShell 里敲npm install -g anthropic-ai/claude-code这个-g就是全局安装的意思。安装过程会从 npm 仓库拉包网速正常的话一两分钟就完事。装完之后再新开一个 PowerShell 窗口敲claude --version能返回版本号就说明装成功了。如果提示找不到命令九成是 3.2 节说的全局目录没进 PATH回去检查。提示如果你公司网络对 npm 仓库有限制安装可能会卡住或者超时。这种情况可以配一下 npm 的镜像源或者找 IT 确认网络策略。具体怎么配这里不展开属于网络环境问题不是 Claude Code 本身的问题。3.4 安装卡住或报错的排查思路npm 安装过程中常见的报错有几类。一类是权限错误提示EACCES或者EPERM这通常是因为全局目录没有写权限。解决办法是用管理员身份开 PowerShell 再装或者把 npm 全局目录改到一个你有完全控制权的路径下。另一类是网络超时提示ETIMEDOUT或者ECONNRESET。这种先重试一次还不行就检查网络。还有一类是 Node 版本不兼容报错里会明确说需要哪个版本以上照着升级 Node 就行。排查的时候记住一个原则报错信息里最关键的是错误码和它后面那句话前面一大堆堆栈信息可以先跳过。比如看到EACCES就直接往权限方向查看到ETIMEDOUT就往网络方向查效率高很多。4. PowerShell 执行策略那个拦住你的隐形墙4.1 执行策略为什么会拦脚本PowerShell 有一个安全机制叫执行策略Execution Policy默认情况下它不允许运行任何脚本文件。这个设计的初衷是防止恶意脚本在你不知情的情况下执行。但问题是很多开发工具的安装脚本、配置脚本都是 .ps1 文件执行策略一拦脚本就跑不起来。Claude Code 本身是通过 npm 安装的不直接依赖 PowerShell 脚本但你在配置环境、跑一些辅助脚本的时候可能会撞上这堵墙。典型报错是无法加载文件 xxx.ps1因为在此系统上禁止运行脚本。看到这个就说明执行策略在拦你。4.2 查看和修改执行策略先看一下当前策略是什么Get-ExecutionPolicy如果返回Restricted那就是最严格的限制啥脚本都不让跑。修改的话推荐改成RemoteSigned这个策略的意思是本地写的脚本可以跑从网上下载的脚本需要有数字签名才能跑。对开发者来说这是个比较平衡的选择既方便又不至于太危险。修改命令需要管理员权限的 PowerShellSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这里的-Scope CurrentUser表示只对当前用户生效不影响系统其他用户也不需要管理员权限。如果你有管理员权限也可以不加这个参数改成全局生效。改完再Get-ExecutionPolicy确认一下返回RemoteSigned就对了。4.3 执行策略改完还是不生效怎么办有时候你改了策略但跑脚本还是报同样的错。这种情况通常是策略作用域的问题。PowerShell 的执行策略有多个作用域优先级从高到低是Process当前进程 CurrentUser当前用户 LocalMachine本机。如果某个更高优先级的作用域设了Restricted你改低优先级的没用。查所有作用域的策略Get-ExecutionPolicy -List这会列出每个作用域当前的设置。如果发现MachinePolicy或者UserPolicy是Restricted那说明是组策略在管这种情况一般是公司电脑的 IT 统一设的你自己改不了得找 IT 协调。注意不要为了图省事直接把策略设成Unrestricted那等于把所有脚本限制都关了安全风险太大。RemoteSigned是开发场景下比较合理的折中。4.4 PowerShell 版本确认与升级Claude Code 和一些现代工具对 PowerShell 版本也有要求。Windows 10 和 11 自带的通常是 PowerShell 5.1这个版本够用。但如果你想用一些新特性可以装 PowerShell 7也叫 PowerShell Core它是跨平台的功能更强。查当前版本$PSVersionTable.PSVersion如果显示 5.1日常用没问题。PowerShell 7 的安装方式是从微软官方仓库下载 msi 安装包或者用 winget 装winget install Microsoft.PowerShell装完之后PowerShell 7 和 5.1 是共存的你可以同时保留两个。在 Windows Terminal 里可以配置不同的配置文件来分别启动。5. 装完之后验证、初始化与日常使用要点5.1 完整的验证清单环境搭完之后跑一遍完整验证确保每个环节都通。按顺序敲这些命令git --version node --version npm --version claude --version四条都返回版本号说明基础环境没问题。然后进一个你的项目目录试试 Claude Code 能不能正常启动cd 你的项目路径 claude第一次启动可能会让你做一些初始化配置比如登录账号、选择偏好设置之类的跟着提示走就行。5.2 首次使用的初始化配置Claude Code 第一次运行时会引导你完成一些初始设置。这个过程会涉及到账号认证按照终端里的提示操作即可。配置信息一般会存在用户目录下的一个配置文件夹里后续想改的话可以找到对应的配置文件手动调整。初始化完成后你可以在项目目录里直接跟 Claude Code 对话让它帮你读代码、改代码、跑命令。它的工作方式是在当前目录下操作所以一定要在正确的项目目录里启动它不然它操作的就是别的目录了。5.3 和 VS Code 配合使用的配置很多人习惯在 VS Code 里写代码同时用 Claude Code 做辅助。这两者可以配合得很好。一种方式是在 VS Code 的集成终端里直接跑 Claude Code这样代码编辑和 AI 辅助在同一个窗口里完成不用来回切。VS Code 的集成终端默认可能是 CMD 或者 PowerShell建议设成 PowerShell。在设置里搜terminal.integrated.defaultProfile.windows改成PowerShell。这样每次开集成终端都是 PowerShell环境变量和 PATH 都和你外面用的一致。如果集成终端里claude命令找不到但外面 PowerShell 里能用那多半是 VS Code 没继承到最新的 PATH。重启一下 VS Code 通常能解决因为 VS Code 启动时会读取系统环境变量改了 PATH 之后需要重启才能生效。5.4 日常使用中的几个实用习惯用熟之后有几个习惯能让你少踩坑。第一保持 Node.js 和 Claude Code 定期更新。npm 全局包更新用npm update -g anthropic-ai/claude-codeNode.js 本身的更新建议直接下新版安装包覆盖安装比用包管理器升级稳。第二项目目录尽量用英文路径避免空格和特殊字符。Windows 上中文路径和带空格的路径在某些工具链里会出问题虽然 Claude Code 本身对中文路径支持还行但 Git 和一些底层工具不一定。用纯英文、无空格的路径最省心。第三遇到报错先看错误码再搜解决方案。前面提过错误码是最关键的线索。把错误码加上工具名一起搜基本都能找到对应的解决办法。6. 常见报错速查与我的实操体会6.1 高频报错对照表把我在实际安装和使用中遇到的高频报错整理成一张表方便对照排查报错信息关键词根本原因解决方向不是内部或外部命令PATH 未配置或终端未刷新检查 PATH新开终端禁止运行脚本PowerShell 执行策略限制改为 RemoteSignedEACCES / EPERM全局目录无写权限管理员运行或改目录ETIMEDOUT / ECONNRESET网络问题重试或检查网络找不到 git 命令Git 未加入 PATH手动补 PATH版本不兼容Node 版本过低升级 Node.js这张表覆盖了九成以上的常见问题。遇到报错先在这张表里对一下能快速定位方向。6.2 我踩过的几个真实坑说几个我自己踩过的、文档里不太会写的坑。第一个是装完 Git 忘了新开终端在当前窗口反复试git --version一直失败还以为装错了重装了两遍才发现是终端没刷新。这个坑看似低级但真的很容易犯因为人的直觉是装完就能用不会想到环境变量需要新终端才生效。第二个是npm 全局目录的 PATH 问题。我有一台机器上 Node.js 装完之后npm 全局目录没自动进 PATH导致claude命令死活找不到。当时排查了半天最后用npm config get prefix查到目录手动加进 PATH 才解决。这个问题的隐蔽性在于npm install -g本身是成功的没有任何报错但装完就是用不了。第三个是执行策略的作用域问题。我在一台公司电脑上改了 CurrentUser 的策略但跑脚本还是被拦后来用Get-ExecutionPolicy -List一查发现 MachinePolicy 是 Restricted是 IT 统一设的自己改不了。这种情况只能找 IT硬折腾没用。6.3 给新手的几条实在建议如果你是完全的新手我给几条实在的建议。第一按顺序来别跳步。先 Git再 Node最后 Claude Code每一步验证通过再往下走。跳步的话出了问题很难定位是哪一环的锅。第二每装完一个组件就新开终端验证。这个习惯能帮你把问题隔离在单个组件里而不是攒到最后一起爆发。第三把安装路径和版本号记下来。出问题的时候这些信息能帮你快速判断是不是版本兼容问题。比如 Node 版本、Git 版本、Claude Code 版本记在备忘录里排查时直接看。第四别怕重装。环境配乱了与其花两小时排查不如花二十分钟重装一遍。当然前提是你知道正确的安装步骤所以第一次装的时候把关键选项记清楚很重要。6.4 环境配好之后能做什么环境搭好只是起点Claude Code 真正好用的地方在于它能深度参与你的开发流程。你可以在项目里让它帮你读代码、解释逻辑、生成改动、跑测试命令。它和 Git 配合能自动生成提交信息、查看改动 diff。和 VS Code 配合能在编辑器里直接调用。我个人的体会是环境配置这一步虽然烦但一次配好能用很久。Windows 上的坑主要集中在 PATH 和执行策略这两块把这两个搞明白后面基本就顺了。真正影响效率的不是安装本身而是遇到问题时不知道往哪个方向排查。希望这篇里的排查思路和对照表能帮你在遇到问题时快速定位而不是对着报错干瞪眼。最后分享一个小技巧如果你要在多台 Windows 机器上配同样的环境可以把关键的配置命令写成一个 PowerShell 脚本比如设置执行策略、检查 PATH、验证版本这些新机器上跑一遍脚本就能快速确认环境状态。脚本不用复杂几条检查命令串起来就行省得每次手动敲一遍。