最近我把 Claude Code 在 Windows 上完整装了一遍，从环境准备、命令执行到账号授权跑通，前前后后折腾了小半天，中间踩了几个坑，查了不少资料，才把整个过程理顺。Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手，安装方式本身不复杂，本质就是一个 npm 包，但真正装的时候，Windows 环境下的细节远比官方文档写的要多。
这篇文章是我在 Windows 上亲测过的完整安装记录，覆盖了前置依赖、每一步命令与参数、两种登录方式、以及装完后我遇到的一堆报错和排查思路。不管你是刚接触命令行 AI 工具的新手，还是已经在 Mac / Linux 上用过、想切到 Windows 环境的开发者，这篇内容基本能让你少走我走过的弯路。
1. 安装前的准备：先弄明白 Claude Code 在 Windows 上依赖什么
1.1 为什么硬性依赖是 Node.js 和 Git
很多人看到 Claude Code 的第一反应是：一个 AI 编程助手，为什么要装 Node.js，还要装 Git？这个疑问很正常，我第一次看到系统要求的时候也愣了一下。
先厘清概念。Claude Code 本身是一个 npm 包，包名是@anthropic-ai/claude-code。npm 是 Node.js 自带的包管理器，所以你想通过npm install -g安装它，前提就是本机已经有一套可用的 Node.js 运行时。安装完成后，你在终端输入claude命令时，实际执行的是 Node.js 脚本，没有 Node.js 就没有办法启动这个工具。
Node.js 版本有硬性底线要求：必须是 18 及以上。实际上我建议直接装 20 LTS 或更新版本。版本太旧的话，Claude Code 内部的语法和 API 调用会有兼容性问题，装完启动即报错，排查起来非常难受。
Git 的作用则体现在登录授权环节。Claude Code 第一次启动时，需要你用 Claude 或 Anthropic 账号完成 OAuth 授权，终端会弹出授权地址和一次性验证码，浏览器走完流程后把授权回传给本地进程。这个回调链路的底层依赖就是 Git 的环境配置。如果你的 Git 没装好，或者没有加入系统的 PATH 环境变量，授权流程会卡住，终端一直提示等待授权，但浏览器那边怎么操作都没有反馈。
所以 Node.js 和 Git 不是可选项，而是两个硬性前置条件。缺了任何一个，后面都会出问题。
1.2 Windows 环境检查清单
在真正开始安装之前，我建议花两分钟做一个环境确认，避免装到一半才发现基础环境有问题。
依次检查这几点：
- 操作系统版本：建议 Windows 10 1809 以上或 Windows 11。版本太老的系统在 PowerShell 和 npm 的支持上会有些麻烦，不是不能用，而是出现奇怪问题的概率高。
- 打开 PowerShell 确认 Node 和 Git 是否已存在：分别输入
node -v和git --version，如果提示“不是内部或外部命令”，说明对应组件还没装，或者没加入 PATH。 - 查看 npm 当前源地址：执行
npm config get registry。如果显示的是默认官方源，后续安装时网速一般会比较慢，可以考虑切换镜像源，这一点我在下一章详细说。 - 确认账号：准备一个可用的 Claude 或 Anthropic 账号，因为首次启动必须走登录授权。没有账号的话，授权环节是绕不过去的。
还有一个终端选择的问题。Windows 下推荐用 PowerShell 或 Windows Terminal，不建议用老式命令提示符 CMD。Claude Code 的交互界面在 CMD 里偶尔会出现渲染错位的问题，尤其是我一开始在 CMD 里启动，发现响应很慢，切到 PowerShell 之后就顺畅多了。
2. Windows 完整安装流程（从零到跑通）
2.1 安装 Node.js 与 Git 的关键选项
如果确认本机还没有 Node.js 和 Git，可以从官方网站下载安装包。两个软件的默认安装流程都比较傻瓜，但有几个关键选项必须注意，否则后面会有坑。
Node.js 安装时有一个“Add to PATH”的选项，务必勾上。这个选项决定了你后续能不能在 PowerShell 里直接敲node和npm命令。很多人装完 Node.js 之后node -v报错，十有八九就是这个选项没勾。装完后建议重新打开一个新的 PowerShell 窗口，让 PATH 环境变量刷新一次，不要用安装前的旧窗口。
Git 安装时同样要注意 PATH 相关选项。Windows 版 Git 安装到“Adjusting your PATH environment”这一步时，推荐选默认的中间档，也就是“Use Git from the command line and also from 3rd-party software”，这样 Git 会在命令行的全局 PATH 里可用，Claude Code 在授权回调时才能在本机正确找到 Git。
装完后按顺序验证三个命令：
node -v npm -v git --version这三个命令都能正常输出版本号，说明环境准备完毕。
2.2 npm 源配置：第一次避免安装超时
Claude Code 的 npm 包体并不小，加上依赖文件，整包下载要花一点时间。如果你使用的是 npm 默认的官方源，在国内网络环境下很常见的问题就是卡在sill idealTree阶段，或者直接报ETIMEDOUT，等待几分钟后以失败告终。
解决方式很直接，先把 npm 源切换成国内镜像源。执行：
npm config set registry https://registry.npmmirror.com切换后再执行npm config get registry，确认输出的是镜像源地址，就可以继续安装。
这个操作是可逆的，如果后续你需要用官方源，再执行一次配置改回来就行。镜像源和官方源在大多数场景下内容是一致的，对安装结果没有影响。
不过我要多说一句：npm 源解决问题只是安装阶段的事，Claude Code 运行时连的是 Anthropic 的 API 服务，那个服务不在镜像源范围内，所以不要以为换了 npm 源就能解决运行时连接问题。运行时连通性我在后面单独讲。
2.3 全局安装与版本验证
环境准备就绪后，安装命令就一行：
npm install -g @anthropic-ai/claude-code-g参数表示全局安装，这样claude命令会被注册到系统全局路径下，你不论在哪个目录打开终端，都能直接调用。
安装完成后立刻验证：
claude --version正常情况下会输出版本号，类似1.0.x。如果你在这里遇到“claude 不是内部或外部命令”的提示，问题出在 npm 的全局 bin 目录没有加进系统 PATH。排查方式是先查看 npm 的全局目录：
npm config get prefix得到的路径就是 npm 全局安装目录，找到其中的cmd子目录，把它加入系统环境变量 PATH，然后重新打开终端再试。
我实操的时候，这里踩了一个隐蔽的坑：安装完 Claude Code 之后，原来的终端窗口一直提示找不到命令，我改完 PATH 之后重开终端就好了。原因就是 PATH 环境变量的修改只对新开的窗口生效，旧窗口里不会自动刷新。
2.4 首次启动、两种登录授权方式与连接验证
安装完成后，切换到你的项目目录，或者先建一个临时测试目录：
mkdir claude-test cd claude-test claude首次启动时，终端会显示一段欢迎说明，然后进入登录引导。
登录有两种方式。第一种是浏览器授权模式，终端会给出一个 URL 和一次性 code，你复制到浏览器，打开地址，完成账号登录后回到终端确认即可。第二种是 API Key 模式，也就是提前设置好ANTHROPIC_API_KEY环境变量后启动，跳过 OAuth 授权流程。
我建议第一次使用用浏览器授权模式，完整跑一遍登录流程。这个模式可以顺带检验 Git、网络、跨进程回调整条链路是否通畅。如果这个流程走得通，说明环境本身比较干净。
浏览器授权成功后的表现是：浏览器页面出现“授权成功”之类的反馈，然后回到终端按回车，进入 Claude Code 的交互界面。如果回车后终端一直没有反应，或者提示等待授权但不继续，我后面会专门讲排查思路。
启动成功后会进入一个类似 REPL 的交互式终端，顶部有一个输入框。这里我建议做一个简单验证，比如输入：
看看当前目录下有哪些文件Claude Code 会真实读取目录内容，并在交互区返回结果。再让它写一个小脚本，比如计算当前目录的文件大小总和，如果它能输出可运行的代码，说明整条链路已经通了。
我测试时的实际体验是：它能在几秒内完成目录扫描并给出一段可以直接运行的 Python 脚本，响应速度和准确度都让我满意。
2.5 安装过程的完整命令脚本
如果你希望一次性完成环境准备到安装的所有步骤，可以直接按顺序执行下面这段命令。前提是你已经装好 Node.js 和 Git：
# 1. 切换 npm 源，加快下载速度 npm config set registry https://registry.npmmirror.com # 2. 确认当前 Node 和 npm 版本 node -v npm -v # 3. 全局安装 Claude Code npm install -g @anthropic-ai/claude-code # 4. 查看版本确认安装成功 claude --version # 5. 进入一个目录并启动 cd D:\projects\claude-test claude启动后的登录流程由终端引导完成，按提示操作即可。整个安装过程，正常网络环境下大概需要三到五分钟。
3. 安装后的配置优化与多终端接入
3.1 settings.json 配置解析
Claude Code 的配置存放在用户目录下的.claude文件夹。Windows 系统下的完整路径是：
C:\Users\你的用户名\.claude\settings.json这个 JSON 文件控制着 Claude Code 的行为偏好，包括默认模型、权限模式、自动化操作策略等。第一次启动时可能还没有这个文件，直到你在交互界面中修改过设置，系统才会自动生成。
我目前用的一个简单配置是这样的：
{ "model": "claude-sonnet-4-20250514", "permissions": { "defaultMode": "acceptEdits" }, "env": {} }几个配置项的含义分别说一下：
model：选择默认使用的模型，不同模型的上下文能力和响应速度有差异。如果你不是特别清楚该用哪个模型，保持默认即可，不用特意写。permissions.defaultMode：控制 Claude Code 修改文件时的权限策略。acceptEdits表示自动接受它对文件内容的编辑操作，适合你已经信任这个工具对项目的改动时使用。env：用于设置一些额外的环境变量，一般保持空对象就好。
修改配置文件前建议先做备份。JSON 格式比较严格，少一个逗号或者多一个引号都会导致启动报错，而且报错信息不直观，排查起来费时间。
3.2 API Key 方式接入
如果你已经有 Anthropic 的 API Key，想跳过浏览器授权这一步，可以改用环境变量方式接入。
PowerShell 下临时设置环境变量的命令：
$env:ANTHROPIC_API_KEY = "你的key"设置后直接启动claude，它会识别到这个环境变量并跳过登录流程。
如果希望长期生效，可以用setx命令：
setx ANTHROPIC_API_KEY "你的key"不过setx设置的环境变量只对之后新开的终端窗口生效，当前窗口不会立即更新，这一点要注意，不要设置完直接在同一个窗口里启动，然后怀疑环境变量没生效。
两种方式对比一下：
| 接入方式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 浏览器 OAuth | 流程直观、配置少 | 依赖 Git 和网络回调链路 | 个人开发者、首次使用 |
| API Key | 环境隔离好、不依赖 Git 链路 | 需要额外申请 Key，且按量计费 | 脚本化调用、自动任务、团队统一管理 |
3.3 WSL 与 Git Bash 接入差异
很多在 Windows 上做开发的用户，实际工作环境并不是原生 Windows 终端，而是 WSL（Windows Subsystem for Linux）或 Git Bash。这两种环境接入 Claude Code 的流程，和原生 Windows 有一些细微差别。
先说 WSL。在 WSL 里安装 Claude Code，流程本质上和 Linux 一致：先确认 WSL 内部的 Node.js 和 Git 已安装，然后执行npm install -g @anthropic-ai/claude-code。需要注意的是，WSL 内部有自己独立的文件系统和用户目录，所以 Claude Code 的配置文件也独立存放在 WSL 的用户目录下。你在原生 Windows 下改了配置，WSL 里默认不会同步生效，两边是两套环境。
WSL 里做登录授权时，弹出的浏览器地址可以在 Windows 浏览器中打开，完成授权后回到 WSL 终端继续操作，这没问题。
Git Bash 的情况类似，要用的是 Git Bash 自带的 bash 命令环境。安装命令和 Windows 原生终端一致，但 PATH 的配置路径可能不同，需要额外留意 npm 的全局目录是否在 Git Bash 的 PATH 里。
我的建议是：如果你日常主力环境是 WSL，直接在 WSL 里装一份完整的 Claude Code，不要指望原生 Windows 的那份能直接在 WSL 里调用。反之亦然。分开管理，两套环境互不干扰，反而省心。
3.4 Claude Code 常用命令速查
把它当成一个日常工具箱来用，记住几个高频命令就够了。
| 操作 | 命令 |
|---|---|
| 查看版本 | claude --version |
| 更新到最新版 | npm install -g @anthropic-ai/claude-code@latest |
| 启动交互模式 | claude |
| 查看当前配置 | claude config list |
| 查看帮助 | claude --help |
| 退出交互界面 | 输入/exit |
更新操作比较重要，Claude Code 迭代速度很快，隔一段时间执行一次更新，可以体验到最新的模型能力和工具链优化。
4. 常见问题与避坑实录
4.1 高频问题速查表
我把安装和使用中最高频的问题整理成了一张速查表，先看症状再找原因，解决效率会高很多。
| 症状 | 原因 | 处理方法 |
|---|---|---|
claude不是内部或外部命令 | npm 全局目录不在 PATH | npm config get prefix找到目录，加入系统 PATH 后重开终端 |
| npm install 长时间卡住或超时 | 默认源访问慢 | 切换 npm 镜像源后重装 |
| 登录授权后终端无反应 | Git 未装或未加入 PATH；网络回调异常 | 确认 Git 环境，重新跑授权流程 |
| 启动即报语法错误 | Node.js 版本过低 | 升级 Node.js 到 18 及以上 |
| 修改配置后启动报错 | settings.json 语法错误 | 备份原配置，检查 JSON 格式 |
| 升级后行为异常 | 旧版本缓存残留 | 卸载重装：npm uninstall -g @anthropic-ai/claude-code |
这张表里前三个问题我在实际安装中全部遇到过，下面展开说一下排查思路。
4.2 我的三个踩坑记录
第一个坑是claude命令找不到。我一开始安装完就在当前终端里执行claude --version，结果提示“不是内部或外部命令”。我当时的第一反应是安装没成功，但实际上 npm 已经装好了，问题在于 npm 的全局目录没有被系统识别。用npm config get prefix查到全局目录后，把它加入 PATH，重开终端就好了。这里最关键的一步是重开终端，PATH 环境变量的修改不会自动刷新到已打开的窗口里。
第二个坑是登录授权卡住。第一次启动 Claude Code，终端弹出了授权地址和 code，我复制到浏览器完成了登录，但回到终端后它一直显示“等待授权完成”，没有任何反馈。我排查了很久，最后发现问题出在 Git 上——我机器的 Git 安装时没有把可执行文件目录加进 PATH，导致 OAuth 回调流程在本地找不到 Git，链路中断。重新安装了 Git 并勾选 PATH 选项后，再次运行登录流程就顺利通过了。
第三个坑比较隐蔽，也更容易被忽略：WSL 和原生 Windows 的配置各自独立。我在原生 Windows 里修改了 settings.json，然后跑到 WSL 里启动 Claude Code，发现配置完全不生效。后来才意识到 WSL 内部是独立的文件系统和用户目录，配置也需要在 WSL 里单独设置。这个问题不算报错，但很容易让人困惑。
4.3 清理、重装与版本升级
Claude Code 的版本更新频率很快，新版本通常伴随着模型能力的增强和工具链的扩展。更新命令很简单：
npm install -g @anthropic-ai/claude-code@latest但如果你遇到升级后行为异常，比如配置文件加载报错、命令响应异常，我建议直接干净地卸载重装：
npm uninstall -g @anthropic-ai/claude-code然后重新执行安装命令。卸载不会清除你的配置文件和登录状态，所以不用担心重新登录的问题。
如果连配置都想清掉，可以手动删除C:\Users\你的用户名\.claude目录，然后重新启动 Claude Code，它会以全新的初始状态运行。这个操作比较彻底，建议在备份好配置文件之后再执行。
5. 写在最后的个人体会
这次在 Windows 上把 Claude Code 从头到尾装通之后，我最大的感受是：工具的安装门槛并不高，真正费时间的反而是环境细节。一个 PATH 没配好、一个 Git 没加进环境变量，就能让整个流程卡住半小时。如果你也是第一次在 Windows 上安装，建议耐心一点按顺序走，每完成一步先做一步的验证，不要跳过检查直接往下冲。
另外，装好之后不要急着在大型项目里直接开工，先在一个空目录里试几轮交互，让它写个小脚本、读一下目录、改一个文件，把它的工作方式摸清楚再实际使用。这个工具用熟了之后，效率提升是很明显的，尤其是批量重构和代码审查这类场景。根据我个人经验，先把环境基础打牢，后续使用才能少踩坑。
