Windows 下 Claude Code 安装配置指南：从 Node.js 到环境变量与常见问题

1. 装之前先搞清楚：Claude Code 在 Windows 上到底该怎么装

很多人第一次看到 Claude Code 的安装命令，以为这就是一行npm install的事，结果在 Windows 上装了半天不是claude命令找不到，就是装完了卡在登录界面。先说结论：Claude Code 在 Windows 上能不能顺利跑起来，取决于三件事同时成立——Node.js 环境、npm 全局安装目录的 PATH、以及一份有效的登录凭据。缺任何一个，都会出现看起来很莫名其妙的报错。

Claude Code 本质上是一个跑在终端里的编程代理，你可以把它理解成一位坐在你旁边、可以直接操作你电脑文件的结对编程伙伴。你用自然语言告诉它需求，它去读代码、改文件、执行命令、跑测试，再把结果反馈给你。它不依赖某个特定的 IDE，也不强制你用某种编辑器，终端本身就是它的主战场。这也正是它在 Windows 上安装会有一点特殊性的原因：它跑在 Node 生态上，又依赖终端交互，而 Windows 的终端、PATH、权限机制跟 macOS/Linux 有很大不同。

这篇安装指南适合谁？适合想在自己的 Windows 电脑上亲手把 Claude Code 装好、并真正用起来的开发者。无论你是刚接触终端的新人，还是写过好几年代码的老手，只要你想在命令行里多一个会写代码、能改代码的帮手，按这篇的顺序走，能少踩很多坑。我不会只把命令丢给你，还会讲清楚每条命令为什么要这么写、报错时应该查哪里。

再说一下这篇文章的整体顺序：先把 Node.js 环境准备好，再安装 Claude Code 本体，然后完成登录和初始化，接着把配置文件和环境变量讲透，最后集中整理我在真实操作里遇到过的各种报错和解决办法。下面开始。

1.1 Claude Code 解决的问题：从“聊天窗口”到“执行操作”

传统的 AI 编程工具大多是一个聊天气泡：你复制报错进去，它给你一段建议，然后你自己手动改代码。Claude Code 不一样的地方在于，它可以真正读写你本地项目的文件、运行命令、查看运行结果，再根据结果决定下一步动作。它不是只给方案，而是直接执行方案。

这种模式的优点是效率极高。比如你让它“给这个接口加上超时重试，重试间隔用指数退避”，它会自己去找到对应文件、修改代码、然后跑一下测试给你看。你不需要先告诉它项目结构，也不需要手动把文件内容贴给它——它自己会看。

在 Windows 上，这种能力会带来一些独特的好处。PowerShell 和 Windows Terminal 本身就是可以用来执行命令、跑脚本、操作文件系统的地方，Claude Code 能把你这些操作串起来。装好之后，你就相当于在终端里多了一个熟悉项目代码、能动手改文件的助手。

1.2 一次安装要打通的“三条链路”

网上很多教程只说了一条安装命令，但实际安装过程其实要打通三条链路：

第一条是 Node.js 运行时，它提供node进程和npm包管理器，Claude Code 这个工具本身就是一个 npm 包，没有 Node 环境一切都是空谈。

第二条是 npm 全局安装目录的 PATH，也就是说系统要能在任何路径下找到claude这个可执行文件。很多人在终端里输入claude提示“不是内部或外部命令”，问题就出在这一环。

第三条是登录认证，没有有效的登录凭据或 API Key，即使命令已经装好、版本号也打印出来了，真正运行时依然会被拦在授权之外。

这三条链路之间是有依赖关系的，所以安装顺序也建议按环境变量 → 本体安装 → 登录配置来。你可以把 Node.js 想象成汽车发动机，npm 是装轮胎的工具，PATH 是传动轴，登录则是车钥匙。先有点火的可能，再挂挡，最后才能踩油门。

2. 环境准备：把 Node.js 装到“可用”的程度

2.1 为什么 Node.js 的版本会直接影响成败

在 Windows 上装 Claude Code，第一个决定成败的关键不是 Claude Code 本身，而是 Node.js 的版本。Claude Code 要求 Node.js 18 及以上，我个人建议直接用 20 或 22 的 LTS 长期支持版本。版本太低，很多语法特性和 API 都不被支持，包根本跑不起来；版本太高也不推荐，一些依赖原生的模块可能还没有跟进，容易在安装或运行阶段出奇怪的兼容问题。

这个原理其实很直白：CLI 工具本身是用 JavaScript/TypeScript 写的，最终跑在 Node 运行时上，Node 的版本决定了它能使用的语言特性和内置 API。你可以去 Node 官网下载 LTS 版本的 .msi 安装包，不用纠结 LTS 具体是 20 还是 22，挑最新的 LTS 版本就行。

2.2 下载安装 Node.js 时容易被忽略的三个细节

下载 Node.js Windows 安装包时，官方页面会有两个大按钮，一个写着 LTS，一个写着 Current，一定选 LTS。安装过程大部分人都能一路 Next 点完，但有几个细节值得注意。

第一个细节是安装向导里默认勾选了“Add to PATH”选项，一定要确认这个勾选是选中的。它会把 Node.js 的可执行目录写进系统环境变量，这样你在任何终端里都能直接使用node和npm命令。有些人安装时手快取消了这个选项，后面就得手动改环境变量，麻烦得多。

第二个细节是安装完成后必须彻底重开终端窗口。很多 Windows 用户安装完 Node.js 后，直接在原来的终端窗口里敲node -v发现命令不存在，就以为装失败了，其实只是终端没有刷新新的环境变量。正确做法是把 PowerShell 或 Windows Terminal 完全关闭，再重新打开一个窗口。这里可以类比成手机装了新 App，但桌面图标一直没刷新，你要回到桌面才能看到它。

第三个细节是确认安装路径。默认安装目录一般是C:\Program Files\nodejs\，如果你改到了别的盘，后续排查 PATH 时要记住自己改过哪儿，别到时候找不到npm全局目录。

2.3 安装完成后的验证

打开一个新终端窗口，依次执行：

node -v npm -v

正常情况下你会看到类似v20.x.x和10.x.x的版本输出。如果提示“node 不是内部或外部命令”，不用慌，先排查 PATH。在系统设置里搜索“环境变量”，查看用户变量或系统变量里的Path是否包含 Node.js 的安装目录。如果确实没有，手动把C:\Program Files\nodejs\加进去，保存后重开终端。

另外一个小建议是：如果你电脑上会同时折腾多个 Node 项目，可以考虑 nvm-windows 这个版本管理工具。但要注意，nvm-windows 安装时最好以管理员身份运行，否则后面切换版本时符号链接容易出错。如果你只是为了让 Claude Code 跑起来，装一个 LTS 版本的 Node.js 就足够了，不用额外引入变量。

2.4 终端选型：PowerShell、Windows Terminal、Git Bash 选哪个

Claude Code 是一个交互式 CLI 程序，对终端的颜色渲染、字体支持和快捷键响应都有一定要求。Windows 上你可能有多个终端可选，这里说说我的实际感受。

首选是 Windows Terminal 里配置好的 PowerShell。Windows Terminal 对 ANSI 颜色转义的支持很完整，Claude Code 输出的高亮、彩色代码都能正常显示，字体也比较舒服。Git Bash 也可以用，它对 Linux 风格路径的命令更友好，如果 AI 生成的命令偶尔带着/风格路径，在 Git Bash 里反而不容易出现路径问题。CMD 是最不推荐的选择，很多现代终端支持的快捷键和渲染特性在 CMD 下会失灵，用起来会很别扭。

这里再多说一句：如果你本身就在用 WSL2 做开发，也可以在 WSL2 里安装 Claude Code，安装方式跟在 Linux 上一样。但如果你平时就是在 Windows 文件系统里干活、用 Windows 的 IDE，那就在原生 Windows 上装，不用为了这个工具特地去开一个 Linux 子系统。

2.5 环境变量里藏着的坑

“node -v 明明有输出，但 claude 命令找不到”这类问题，十有八九不是 Claude Code 的问题，而是 npm 全局目录没有在 PATH 里。你可以先执行下面这条命令查看 npm 全局目录的位置：

npm prefix -g

Windows 上通常会输出类似C:\Users\<用户名>\AppData\Roaming\npm的路径。这个目录才是claude命令真正被安装的位置。检查一下你的 PATH 环境变量里有没有这个目录，没有就手动加进去，加完后重开终端。

另一个常被忽略的坑是 npm 全局安装时的权限问题。有些 Windows 系统对AppData\Roaming\npm目录的写入控制比较严格，执行全局安装时会报 EPERM 错误。解决办法有两个：一是以管理员身份打开 PowerShell 再执行安装命令；二是把 npm 全局目录改到当前用户自己的目录下，不依赖管理员权限。我个人推荐第二种，因为以后每次升级工具不用都开管理员窗口。设置方式：

npm config set prefix "C:\Users\<用户名>\npm-global"

然后手动把C:\Users\<用户名>\npm-global加到 PATH 里。这种做法更像是给自己划了一块固定的工具安装区，清爽也省心。

3. 正式安装 Claude Code 本体

3.1 一行命令出来的工具包

确认 Node.js 环境没问题后，打开终端（如果想省事，就以管理员身份打开 PowerShell），执行：

npm install -g @anthropic-ai/claude-code

这里的-g表示全局安装，也就是将工具安装到 npm 的全局目录，而不是某个项目内部。加了这个参数后，你才能在任意目录下执行claude命令。安装完成后，先用版本号验证一下：

claude --version

能正常输出版本号，说明工具本体已经装好，接下来就是登录和初始化的事了。

3.2 PowerShell、Git Bash、CMD 下执行命令有什么不同

本质上安装命令在这些终端里没有区别，因为它们最终都是调用同一个 npm。但在实际体验里差异还是存在的：PowerShell 7+ 对 ANSI 转义的显示很好，安装日志和后续交互界面的颜色都很正常；Git Bash 下如果遇到字符错乱，通常是编码问题，可以检查一下终端的代码页设置；CMD 在这种交互式工具面前显得有点吃力，不推荐用来日常使用。

给 PowerShell 用户一个额外提示：如果你的 PowerShell 执行策略禁止运行脚本，安装过程本身可能没问题，但后续 Claude Code 如果要调用一些 .ps1 脚本时会被系统拦下来。可以执行下面的命令，将当前用户的执行策略调整为允许本地脚本运行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

这个操作只影响当前用户，不会动系统级策略，是比较常规的做法。

3.3 安装卡住、下载慢的通用解法

Claude Code 本体依赖不少 npm 包，首次安装时整体下载量不小。如果你发现安装过程长时间停在某个依赖上不动，可以先把 npm 的 registry 切换到国内镜像源试试：

npm config get registry npm config set registry https://registry.npmmirror.com

npm config get registry可以先看看当前源地址，确认已经切换之后再重新执行安装命令。如果后面想把源换回官方默认地址，执行：

npm config set registry https://registry.npmjs.org/

不想永久改全局配置的话，也可以在安装命令里临时指定镜像源，例如：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

这里说一句：切换镜像源只是为了解决 npm 官方源在某些网络环境下下载慢的问题，属于 npm 用法里的常规操作，不要把它想得太神秘。

3.4 装好了可不一定代表“能用了”

很多人装完claude --version能输出版本号，顿时觉得大功告成，接着运行claude，却被卡在登录流程里。这种情况在 Windows 上尤其常见，原因不是工具坏了，而是 Claude Code 必须在完成授权后才能读写文件、执行命令。

第一次运行时会有一个很明显的提示，告诉你需要访问一个授权链接，或者在终端里粘贴一个授权码。这部分流程下一节会详细展开。你只要记住一个原则：版本号能打印，只代表可执行文件放到了正确位置；能真正进入交互模式，才代表安装链路全部打通。

4. 第一次运行、登录与初始化

4.1 第一次启动后的界面流程

建议第一次启动时先在一个空目录里试。比如：

mkdir D:\claude-test cd D:\claude-test claude

这样做的好处是后面无论它做出什么操作，都不会影响你真实项目里的文件。第一次启动会有一段欢迎信息，紧接着提示进行登录授权。正常情况下，系统默认浏览器会自动打开一个授权页面，你在浏览器里确认之后，回到终端就会看到登录成功的提示，随后进入交互式输入界面。

如果浏览器没有自动打开，终端里一般也会显示出完整登录链接，你手动复制到浏览器里打开就行。授权码或回调确认后，终端会自动完成同步。

4.2 登录认证的三种方式

Claude Code 的认证方式大体有三种，按适用场景不同可以自由选择。

第一种是使用订阅账号直接登录。这种方式适合个人开发者，你有 Claude 的订阅账号，在授权页面确认后，CLI 会拿到对应的访问凭据，后续使用按订阅额度计费。

第二种是使用 API Key。设置环境变量ANTHROPIC_API_KEY，Claude Code 启动时会自动读取。这种方式适合想要更精细化控制用量、按 token 计费的开发者，也可以配合一些中转网关使用。

第三种是通过ANTHROPIC_BASE_URL指向自建的模型网关地址。这常用于团队内部统一管理模型路由的场景，具体地址怎么填要看你所在团队自己的配置。对大多数自己在家装的用户来说，第一种和第二种最常用。

我个人建议，如果只是自己折腾，优先考虑订阅账号登录，完全不需要手动设置环境变量；如果你有 API Key，则在 Windows 用户环境变量里添加ANTHROPIC_API_KEY，而不是只在当前终端窗口临时用set设置。用户级环境变量的好处是下次开新终端依然有效，不用每次启动前重新指定一遍。

4.3 授权失败的几个典型表现

登录这一步，在 Windows 上常见的失败表现有三个。一是浏览器打开了但页面一直在转，这时通常要检查账号状态或者授权页是否过期，刷新页面重来一次。二是终端一直显示“等待验证”，这种情况多半是授权链接复制不完整，或者授权码粘贴时带了多余的空格。三是登录成功后终端立刻退出，这种情况往往和环境变量冲突、.claude 目录权限异常有关，可以先查看终端输出的错误信息，再针对处理。

最不建议的做法是一看到登录异常就重装。CLI 工具的报错信息其实挺直白的，上面会写清楚是网络错误、认证错误还是权限错误，先读报错再动手，能省很多时间。

4.4 首次交互时的权限询问

登录成功进入交互模式后，在你发出第一条指令前,界面底部会出现一个输入框。当你要求它执行某些敏感操作时，它会弹权限询问，比如是否允许读写某个文件、是否允许运行某条命令。

对第一次上手的人，我的建议是：在专门建的测试目录里可以放开权限，先看看它到底是怎么工作的；真正进入重要项目时，再把权限收紧，逐条检查它想执行的命令。如果你启动时用了claude --dangerously-skip-permissions跳过所有权限询问，请务必确认你所在的目录是临时测试目录，而不是存着重要代码的项目目录。这条命令的警告不是闹着玩的。

5. Windows 下的配置文件与项目协同

5.1 Claude Code 会在 Windows 下留下哪些文件

登录完成后，Windows 用户主目录下会出现一个.claude文件夹（完整路径通常是C:\Users\<用户名>\.claude）。这个目录是 Claude Code 的“工作台”，里面比较重要的有：

• settings.json：全局设置文件，用来配置模型、权限、钩子等。
• projects/：以项目为维度的状态记录。
• 各种会话历史、缓存数据。

这个目录不要手动乱删，删掉之后你的登录状态、权限设置、历史会话都会一起丢。我有一次手滑清掉了这个目录，结果所有项目的授权状态都要重新确认一遍，得不偿失。

5.2 settings.json 里最常用的配置

settings.json文件里可以配置的内容不少，最常用的几个字段大概是这些：

{ "model": "claude-sonnet-4-5", "permissions": { "allow": [ "Bash(npm run lint)" ], "deny": [ "Write(README.md)" ] }, "includeCoAuthoredBy": true, "hooks": {} }

model指定默认使用的模型，具体可选值以你登录账号时可用的模型为准。permissions用来做允许和禁止规则，比如允许它运行npm run lint，但禁止它修改README.md。includeCoAuthoredBy控制在用 git commit 时是否附带 AI 合作者署名。hooks则可以在工具启动、执行命令、完成响应等时机插入自定义脚本。

配置文件的修改方式是：先退出正在运行的 Claude Code，改完settings.json后再重新启动，让它重新读取配置。很多配置改完不会热生效，这点要注意。

5.3 环境变量：API Key 和模型怎么配合

如果走 API Key 路线，需要在 Windows 环境变量里配置ANTHROPIC_API_KEY。添加位置在“系统属性 → 环境变量 → 用户变量”中，新建键值对即可。配完记得重开终端。

ANTHROPIC_MODEL这个环境变量也可以设置默认模型。环境变量的优先级通常高于settings.json，所以如果你在配置文件里指定了模型但没生效，先看看是不是环境变量里也设置了模型。两条途径二选一就好，避免优先级冲突把自己搞晕。

5.4 用函数或别名把启动方式变成自己的习惯

Claude Code 命令本身不长，但如果每天要敲很多遍，也可以在终端里做个封装。PowerShell 用户可以在 profile 文件里加：

function cc { claude $args }

这样以后只需要输入cc就能启动。Git Bash 用户可以在~/.bashrc里加上：

alias cc='claude'

封装启动命令不只是图省事，它还可以配合固定参数使用，比如每次用cc /path/to/project启动时自动进入指定目录。当然，这种习惯看个人，不用强求。

5.5 原生 Windows 和 WSL 到底怎么选

这是很多人纠结的问题。我的判断标准很简单：看你的日常代码工作主战场在哪里。

如果你用的是 Windows 文件系统、Windows IDE 和 Windows 上的终端工具，那就在原生 Windows 上安装 Claude Code，这样它能顺着你的项目路径直接操作文件。如果你的项目依赖 Linux 特有的脚本或环境，或者部署目标本身就是 Linux 服务器，那可以考虑使用 WSL2，在 WSL2 里运行 Claude Code 会更贴近 Linux 环境的真实工作状态。

原生 Windows 下有一个小缺点：AI 生成的命令可能会以 bash 为前提，在当前 PowerShell 里执行时会报错。解决办法在下一节会说，核心思路是在指令里明确告诉它当前是什么终端环境。

6. 常见问题与排查实录

6.1 高频问题速查表

下面这张表是我在实际使用中遇到较多的问题和对应解法，先整体看一眼：

6.2 最容易误解的一条：升级带来的连锁反应

Claude Code 迭代速度不慢，升级工具本身不难：

npm update -g @anthropic-ai/claude-code

升级后容易出现两个现象：一是之前能用的配置某些字段失效了，二是某些命令的交互方式变了。遇到这种情况，先运行claude --version确认升级后的版本号，再根据新版本的报错提示去调整settings.json。如果升级后出现很奇怪的运行异常，还可以在空目录里重新初始化一次，看是否还复现问题。

6.3 目录权限引发的“怪问题”

Windows 对C:\Users\<用户名>\.claude这类隐藏目录有自己的一套权限控制。如果你每次启动 Claude Code 都要重新登录，或者登录后状态保存不住，大概率是这个目录的写权限出了问题。排查思路是：检查目录的所有者是不是当前用户，把目录权限重置为当前用户可完全控制。注意不要为了省事直接把整个用户目录的 UAC 关掉，那会让系统安全级别明显下降。

6.4 小心安全软件拦截

Claude Code 会运行本地命令、读写文件，安全软件可能把它识别为潜在风险。如果安装时被拦截，先确认拦截对象确实是 Claude Code 相关的启动器文件，而不是某个来历不明的附加脚本。确认后，在可信目录或可信程序列表里放行即可。如果对某个文件有疑虑，宁可不放行，也不要盲目把所有拦截全部关闭。

7. 装完之后怎么快速上手

7.1 第一句指令从哪里开始

不要在重要项目里开第一枪，选一个空目录或测试目录练手。你可以试试这样写：

• “创建一个 Python 脚本，扫描当前目录下所有大于 100MB 的文件并列出”
• “帮我写一个 README，用 100 字以内说明这个项目是干什么的”
• “在当前目录初始化一个 Git 仓库，并生成第一次 commit”

这些小任务既不会造成破坏，又能很快验证 Claude Code 是否已经具备读写文件、执行命令、访问项目结构的能力。如果这些任务都能顺利跑通，安装链路才算真正完成。

7.2 高频斜杠命令速览

交互模式下，输入斜杠开头的命令可以直接控制工具行为。常用的几个：

• /help查看内置帮助
• /status查看当前上下文、模型和资源占用情况
• /compact压缩长对话上下文，释放上下文窗口空间
• /clear清空当前会话
• /quit退出交互界面

长会话卡顿是交互式工具常见的困扰，/compact很好用，它会在保留关键上下文的同时压缩历史内容，相当于给大脑腾出一部分工作记忆。

7.3 让 AI 写出真正能跑的 Windows 命令

原生 Windows 下最容易遇到的尴尬是：让 Claude Code 执行命令，结果它给你生成的是ls、rm -rf、grep这类 bash 命令，当前 PowerShell 根本不认。解决方法很小，但很关键：在指令里提前说明终端环境。

比如你可以说：“用 PowerShell 命令把测试输出写到test.log”。它会立刻切换到 PowerShell 语法来生成命令。如果项目本身放在 Git Bash 或 WSL 环境里跑，同样按实际环境说明即可。这不是工具笨，而是训练数据里 Linux/macOS 语境占主导，主动声明环境能大幅减少指令执行失败的概率。

7.4 路径分隔符和空格是 Windows 的“老熟人”

Windows 路径用反斜杠，路径里还可能带空格。Claude Code 操作文件时，建议给它相对路径而不是一长串绝对路径。比如：

• 推荐写法：把src/utils/format.js里的某个函数改名
• 不那么推荐的写法：修改C:\Users\me\project\src\utils\format.js

相对路径不仅能让 AI 更快理解项目结构，也能避开 Windows 绝对路径里反斜杠转义和各种空格问题。如果你确实需要操作一个带空格的路径，记得在指令里把路径放在引号里，或者明确说“路径带空格请手动加引号”。

7.5 建议每三天做一次收权检查

交互模式下，遇到权限询问时不要太习惯性地直接回车允许。涉及删除、覆盖、push 这类操作，先看一眼它要运行的完整命令。如果你觉得每次都确认很烦，可以在settings.json里写好 allow/deny 规则，比如只允许它运行npm test，禁止它对某些关键目录执行删除。

我自己的习惯是，在每天正式工作前，先用claude --version和/status看一眼版本和当前配置。特别是升级之后，更值得确认一下配置有没有被重置。安装难度这件事，说穿了真不在那行 npm 命令上，把 Node 环境、PATH 和权限这三样基础理顺，Claude Code 在 Windows 上运行起来并不比在别的平台上差。最后分享一个小技巧：如果你发现启动慢，先看看终端是不是已经从老的 CMD 换成了 Windows Terminal，这个终端层面的差异对交互式 CLI 的体感影响比想象中大得多。