最近好几个朋友私信问的是同一件事：Windows 下怎么把 Claude Code 装起来。其实很多人看到别人在终端里敲几行命令就能让 AI 帮忙改代码，第一反应都是“去官网下载一个客户端”，结果真正开始研究才发现，这东西没有一个像样的 .exe 安装包入口，折腾半天还卡在第一步。我当初在 Windows 上第一次跑通 Claude Code 也绕了不少弯路，这次就把完整过程、每一条命令、终端输出和踩坑点全部整理出来。这篇不是真的贴满截图，但会把关键画面用文字还原，你照着终端输出对号入座就能走通。

先说结论：Claude Code 是一个跑在终端里的 AI 编程助手，不是传统意义的图形软件。Windows 原生想把它装好，真正依赖的其实是 Node.js、npm、PowerShell/Windows Terminal 这一套基础环境。搞清楚这个前提，后面所有问题都会变得简单。

如果你已经有能正常登录的 Claude 或 Anthropic API 账号，并且能在本地终端执行命令，那么这篇内容只围绕一件事：让 Claude Code 稳定跑在 Windows 上，并且装完后知道怎么配置、怎么排错、怎么把它接入日常开发流程。新手建议从前往后读，老手可以直接跳到安装命令和报错对照部分。

1. 安装之前先理清这三件事：终端、Node.js 和 Git

1.1 为什么 Claude Code 不是“下个 exe 双击安装”

Claude Code 本质上是一个 Node.js 命令行程序，官方通过 npm 仓库发布，名字叫 @anthropic-ai/claude-code。安装后它在终端里启动自己的交互界面，支持多行输入、斜杠命令、实时流式输出，甚至能直接操作你的文件系统，前提是它运行在某个项目目录下。

这对长期使用图形界面的人来说有点反直觉。你可以把它理解成“买回家需要自己组装的工具架”，而不是“开箱即用的电饭煲”。想让它工作，必须先有底座：Node.js 运行时、npm 包管理器、一个趁手的终端。Git 不是 Claude Code 运行时的硬性依赖，但只要你想让它在真实项目里干活，基本离不开 Git，所以我会建议一起装掉。

1.2 Node.js 版本怎么选才够稳

Claude Code 对 Node.js 有版本要求，理论上满足 18 以上就能跑，但我实际测试下来最省心的版本是 20 LTS。18 不是不行，只是部分较新的 CLI 功能或依赖包在 18 上偶尔会出现小毛病；22 也可以，但如果不是追求新特性，没必要在环境层面给自己增加变量。

Windows 上安装 Node.js 最省事的方式是直接用 winget，在终端里输入下面命令：

powershell复制winget install OpenJS.NodeJS.LTS

这行命令会安装当前最新的 Node.js LTS 版本。如果你更习惯图形化安装，也可以去官网下载 .msi 安装包，一路 Next，默认配置即可。这里有个容易踩的坑：安装完 Node.js 以后，如果你是在同一个旧终端窗口里继续输入 node -v，很可能会提示找不到命令。这不是没装成功，而是终端的环境变量是在启动时读取的，旧窗口不会自动刷新 PATH，随便打开一个新的终端窗口再执行就正常了。

安装完成后，建议先验证版本：

powershell复制node -v
npm -v

我的输出分别是 v20.18.0 和 10.8.2，如果你系统里 npm 版本比较老，可以先升级一下 npm 本身：

powershell复制npm install -g npm@10

1.3 终端：Windows Terminal 和 PowerShell 选哪个

很多教程默认你用的是 CMD，但 Claude Code 的交互界面在 CMD 里虽然能跑，显示效果不太行，对 ANSI 颜色和 Unicode 符号支持都一般。Windows 自带的 PowerShell 5.1 也能用，但我更推荐先装 Windows Terminal，让日常操作舒服很多。

powershell复制winget install Microsoft.WindowsTerminal

Windows Terminal 不是 Claude Code 的必需品，但它提供的等宽字体渲染、Ctrl+C / Ctrl+V 快捷键、多标签页、自动换行，都会让长时间在终端里聊天和改代码的体验完全不一样。如果你暂时不想装，直接打开 PowerShell 也能继续下面的安装。

2. 安装方式横向对比：我为什么把 npm 当作主路线

2.1 三种能跑通的安装方式与各自的适用人群

Claude Code 的安装方式不止一种。我在 Windows 上实际试过三条路线：npm 全局安装、PowerShell 远程脚本安装、在 WSL 里按 Linux 方式安装。三条线都能跑通，但体验和前置条件差别不小。

先说 PowerShell 远程脚本这条线。它确实很诱人，因为不需要先理解 Node.js 概念，一条命令就直接装完。但这条命令本质上是从互联网拉一个 PowerShell 脚本并立即执行，如果你刚接触终端，第一反应应该是：这个脚本到底干了什么？我是否信任它？而且 Windows 默认的执行策略很可能直接拦住远程脚本，报错信息对新手很不友好。

WSL 这条线则是另一个故事。如果你平时所有开发都在 WSL Ubuntu 里做，那就在 WSL 内部安装 Node.js 再走 npm，完全合理。但如果你只是看到网上说“Windows 上跑开发最好用 WSL”，想都没想就把 Claude Code 装进去，接下来大概率会遇到文件路径混乱、权限提示、网络环境不一致等问题，反而给安装了加难度。

2.2 为什么最终把 npm 全局安装当主路线

npm 全称是 Node Package Manager，Windows 装完 Node.js 以后自动就有。全局安装的意思是把这个包装到系统级目录，安装完成后你可以在任意目录下执行 claude 命令。

这条路线最大的优势是可审计、可回退。你能清楚看到 package 名字、版本号、下载来源；出问题时可以升级、降级、卸载，不会像远程脚本那样把一堆东西塞进系统里难以追溯。另外，npm 本身是前端和 Node 开发者必备工具，既然装 Claude Code 绕不开 Node.js，顺手把 npm 用起来一劳永逸。

如果你当前还没有 Node.js，那么我的建议顺序是：先安装 Node.js 20 LTS，再用 npm 全局安装 Claude Code。别图省事直接跳去执行 PowerShell 脚本，一旦网络里的策略限制或杀毒软件拦截，排查成本比多装一个 Node.js 高得多。

2.3 如果你在 WSL 里装，注意别和 Windows 原生混装

很多人会忽略一点：Windows 上的 PowerShell 和 WSL Ubuntu 里执行的命令是两个世界。如果你在 PowerShell 里用 wsl 进入了 Ubuntu，再执行 npm install -g，装完的 claude 命令只存在于 WSL 内部，Windows PowerShell 里敲 claude 依然找不到。

反过来也一样。如果你在 Windows PowerShell 里装了 Claude Code，回到 WSL 的 Ubuntu 里它也不存在。这个知识点听起来很基础，但我见过太多人在 WSL 提示“适用于 Linux 的 Windows 子系统必须更新到最新版本才能继续”之后一头雾水。真要在 WSL 里用，先执行 wsl --update 把 WSL 内核升到最新，再进到 Ubuntu 里单独安装 Node.js 和 Claude Code，两条线互不干扰。

3. 保姆级完整安装步骤：从验车到登录一次说清

3.1 第一步：在终端里确认 Node.js 和 npm 状态

打开 Windows Terminal 或 PowerShell，先执行一条确认命令：

powershell复制node -v

我机器上的输出是：

text复制v20.18.0

再确认 npm：

powershell复制npm -v

输出类似：

text复制10.8.2

如果你发现 npm 不存在，大概率是 Node.js 没装成功，或者 PATH 没生效。这时候不要急着继续，先重新打开一个新终端窗口再试。如果新窗口还是不行，去系统设置里检查环境变量，看 NODE_HOME 或 Node.js 的安装目录是否在 PATH 中。

3.2 第二步：执行全局安装命令

确认 Node 环境没问题后，直接执行：

powershell复制npm install -g @anthropic-ai/claude-code

正常情况下，命令执行期间 npm 会显示下载进度，最后出现类似输出：

text复制added 263 packages in 32s

不同版本依赖数量会有差异，我装的版本输出是 263 个包。如果网络条件不好，这一步可能卡很久，甚至会报网络错误，问题排查我会在第四部分详细说。

这里强调一个 Windows 上的常见误解：不要用 sudo 来安装 npm 全局包。Windows 原生终端没有 sudo 概念，普通用户也不需要管理员权限来安装 npm 全局包。如果安装时碰到权限类报错，通常不是你权限不够，而是 npm 全局目录没有写入权限或路径配置有问题，直接用管理员身份打开终端并不能根治。

3.3 第三步：验证安装结果，找到 claude 命令的真实位置

安装过程没有报错不代表命令一定可用，先验证版本：

powershell复制claude --version

如果输出类似：

text复制1.0.47

说明基本安装成功。接着建议查一下命令位置，方便后续排查：

powershell复制where.exe claude

我机器上的输出路径是：

text复制C:\Users\你的用户名\AppData\Roaming\npm\claude.cmd

在 Windows 上，npm 全局安装的可执行命令通常是一个 .cmd 文件，不是 .exe 文件。这个细节在后面排查“命令找不到”时非常关键。

3.4 第四步：登录认证，走到这一步才算真正装完

验证完版本后，直接在当前终端里输入：

powershell复制claude

第一次运行时会进入账号认证流程。Claude Code 走的是 OAuth 授权，屏幕上会出现一个链接和验证码，浏览器会被自动打开，或者你可以手动复制链接到浏览器。在浏览器里完成账号登录和授权后，回到终端，看到一个欢迎信息，恭喜，到这里安装才算真正结束。

常见的一个误区是：装完包，但没登录，就开始跟风问“为什么 claude 一直提示认证失败”。Claude Code 不是本地离线小工具，它需要连接 Anthropic 服务才能工作。如果你的账号本身没有相关权限，即使命令装得再正确，运行起来也会卡在权限环节。

4. 安装过程中最容易翻车的四个真实场景：我的 Windows 踩坑记录

4.1 执行策略拦截：PowerShell 拒绝运行远程脚本

我最早用 PowerShell 脚本方式安装时，终端直接弹出一段红色报错：

text复制无法加载文件，因为在此系统上禁止运行脚本。

原因很简单：Windows 默认执行策略是 Restricted，禁止运行任何 PowerShell 脚本。这不是 Claude Code 的问题，而是 Windows 的安全机制。

如果你想查当前策略，执行：

powershell复制Get-ExecutionPolicy -List

想临时修改为允许本地脚本和远程签名脚本，执行：

powershell复制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

RemoteSigned 的意思是：本地创建的脚本可以运行，从远程下载的脚本需要有可信发布者签名。这个设置只对当前用户生效，不需要管理员权限。不过我还是建议，日常开发别把执行策略改成 Unrestricted，安全性和便利性之间的平衡没必要用极端方式换取。

如果你确实要用 irm ... | iex 方式安装远程脚本，也可以不开全局执行策略，而是用一个更“一次性”的方法。在 PowerShell 顶部输入 powershell -ExecutionPolicy Bypass 再执行，只对当前会话生效，但我仍然建议优先走 npm 路线。

4.2 “claude 不是内部或外部命令”的真相：PATH 路径问题

这个坑几乎每个 Windows 新手都会遇到：npm 安装时明明显示成功，但输入 claude 却提示：

text复制claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

遇到这个报错，不要怀疑 npm 没装成功，先执行：

powershell复制where.exe claude

如果没有任何输出，问题基本确定：npm 的全局安装目录不在 PATH 里。

查 npm 全局目录位置：

powershell复制npm prefix -g

官方 Node.js 安装版通常会把 npm 全局目录放在 C:\Users\你的用户名\AppData\Roaming\npm，但这个目录不一定会被自动加入 PATH。解决办法是打开系统环境变量设置，在用户变量 Path 中加入这个目录，然后重开终端窗口。

我见过很多人卡在这里反复重装，这是最没必要的。重装十次也解决不了 PATH 问题，因为包确实装好了，只是系统不知道去哪找它的启动命令。

4.3 npm 卡在下载阶段：看着像死机，其实它在工作

npm 安装时终端偶尔会长时间没有新输出，尤其 Windows 自带的 PowerShell 对进度动画支持不好，你会感觉程序像卡死了。其实不能直接 Ctrl+C，因为 npm 可能在后台持续下载。

建议先做的排查动作是：

powershell复制npm ping

这条命令会测一下 npm registry 是否能正常连通。如果网络正常，耐心等待即可。如果确认网络受限，再考虑是不是 npm registry 本身的问题。最容易忽略的是磁盘空间：全局安装虽然不算大，但如果 C 盘剩余空间太少，npm 解压包的时候会极其缓慢甚至报错。

清理缓存可以用：

powershell复制npm cache clean --force

但要提醒一句，这招不要随便用，它会把 npm 下载过的所有缓存清掉，下一次安装会重新走网络下载，反而更慢。只有当你怀疑缓存文件损坏时才值得尝试。

4.4 WSL 版本提示和双环境混淆：路径、权限各有各的规则

很多人装到一半突然看到一条提示：

text复制适用于 Linux 的 Windows 子系统必须更新到最新版本才能继续。

如果是在 WSL 里折腾时遇到的，先执行：

powershell复制wsl --update

更新完再重新进入 WSL。但要注意，这条消息本身和 Claude Code 无关，它只是说明你的 WSL 内核版本过旧。

更大的坑在路径认知上。Windows 文件系统路径是 C:\Users\xxx\project，WSL 里则是 /home/xxx/project。如果你在 WSL 里运行 Claude Code，却让它去读 C:\Users\xxx\project，大概率会出问题。相反，在 Windows 原生 PowerShell 里运行 Claude Code，它读的是 Windows 路径。搞清楚当前命令跑在哪个终端环境里，能省掉大量排查时间。

5. 装完不等于会用了：目录、斜杠命令与 VS Code 联动

5.1 第一次运行别直接在用户主目录里跑

Claude Code 启动时会把你当前所在目录当作工作根目录，读取该目录下的文件结构。第一次练习，建议先建一个独立的项目目录，不要直接在 C:\Users\你的用户名 这种主目录里跑。

powershell复制mkdir D:\claude-practice
cd D:\claude-practice
claude

为什么这一步很重要？因为 Claude Code 在项目目录里工作时，它可以读取文件、编辑代码、执行命令。如果你直接在用户主目录里运行，它可能会扫描到大量与你当前任务无关的私人文件、配置文件，产生干扰，甚至有误操作风险。独立目录是新手最好的安全带。

5.2 高频斜杠命令：先记住五个就够了

Claude Code 的交互界面支持斜杠命令，最有用的几个是：

这几条命令不需要背，只要记住 /help 永远存在，遇到问题随时可以调出来看。真正长期使用后，你自然会形成自己的常用命令集合。

5.3 用 CLAUDE.md 给项目立规矩

Claude Code 会读取项目根目录下的 CLAUDE.md 文件，把它当作“项目说明书”。这个文件不是必选项，但用了之后效果天差地别。

举个例子，我在一个练习项目里放了这样的内容：

code复制# 项目约定

- 这是一个 Windows 环境下的 Node.js 练习项目
- 代码风格：使用 CommonJS，不用 TypeScript
- 运行测试的命令：npm test
- 遇到不确定的需求时，先列出实现方案让我确认，不要直接改代码

一旦放了这个文件，Claude Code 每次在这个目录里运行都会自动带上这些约束，不需要我反复解释项目背景。它等于是在给 AI 做“上岗培训”，花五分钟写清楚，后面省下的是大量来回纠正的时间。

5.4 在 VS Code 里调用 Claude Code 的两种方式

方式一最直接：在 VS Code 里按 Ctrl+` 打开集成终端，输入：

powershell复制claude

就可以在项目目录里直接对话。这个方式的优点是天然处于项目上下文中，Claude Code 能直接看到当前仓库的文件。

方式二是在 VS Code 扩展市场搜索 Claude Code 相关扩展，安装后可以在侧边栏或命令面板里唤起 Claude Code 界面。插件市场里的扩展可能来自官方也可能来自社区，装之前注意看一下维护方和下载量，避免装到来路不明却要求极高权限的扩展。

对于新手，我推荐先方式一跑熟，再考虑扩展。毕竟终端工作流本身就是 Claude Code 的核心特色，没必要一开始就套一层 GUI，反而掩盖了它的真正玩法。

6. Windows 安装期报错速查：从执行权限到模型名不识别

6.1 高频报错与对应处理对照表

安装阶段报错主要集中在几个类型，整理成表格方便对号入座。

这些其实都不是 Claude Code 本身的安装 bug，绝大多数是 Windows 系统环境变量、执行策略或终端环境的问题。

6.2 关于模型名不识别报错的特别说明

很多人在运行 Claude Code 时会碰到类似这样的模型相关报错：

text复制"deepseek-v4-flash" is not a model this version of Claude Code recognizes

这行报错的意思是：某个位置配置的模型名，在当前版本的 Claude Code 模型列表里不存在。最常见的触发原因是使用了环境变量或配置文件指定了自定义模型标识，而当前 Claude Code 版本并不认识这个标识。

排查方向大概是这样的：

第一步，查版本：

powershell复制claude --version

第二步，检查系统环境变量里是否有 ANTHROPIC_MODEL 之类的配置。在 PowerShell 里执行：

powershell复制Get-ChildItem Env:ANTHROPIC_MODEL

如果有输出，说明你显式设置了一个默认模型名，把它清掉：

powershell复制Remove-Item Env:ANTHROPIC_MODEL

第三步，更新 Claude Code 到最新版。这个报错经常出现在旧版本上，因为我用下来 Claude Code 的更新频率非常高，每次发布几乎都有新模型和模型列表变化。如果代码版本太老，新模型标识自然不识别。

更新命令是：

powershell复制npm install -g @anthropic-ai/claude-code@latest

如果问题依旧，就在交互界面里输入 /model 查看当前会话支持的模型列表，手动选一个官方支持的模型再继续。

6.3 升级和卸载：别在旧版本上死磕

由于 Claude Code 更新频率高，我建议把它当作需要定期更新的工具，而不是装一次就完事。

查看当前全局包版本：

powershell复制npm list -g @anthropic-ai/claude-code

升级：

powershell复制npm install -g @anthropic-ai/claude-code@latest

卸载：

powershell复制npm uninstall -g @anthropic-ai/claude-code

卸载完以后，如果你确定不再使用，可以顺手清理用户目录下的 .claude 配置文件夹。Windows 上它的位置是：

text复制C:\Users\你的用户名\.claude

这个目录里有登录凭据、历史会话、项目配置。直接删除可以彻底清掉所有状态，但也要考虑是否需要备份，因为里面没有容易重建的东西。

7. 用了几周之后的几点真实建议：从“能跑”到“好用”

7.1 Claude Code 到底适合哪类 Windows 用户

从实际体验来看，Claude Code 不是给所有人准备的“零门槛 AI 助手”。它适合的人群有三类：已经习惯了命令行操作、平时写代码经常跨文件修改、愿意用 Git 做版本管理的开发者。如果你目前对终端的认知还停留在“输入 cd 就害怕”的程度，我更建议先在 VS Code 这种图形环境里熟悉编程基础，再切换到 Claude Code。

它最大的竞争力不是“能聊天”，而是能直接在项目里做实际修改。正因为如此，它的使用门槛也更高——你必须理解项目结构、依赖关系、版本控制，否则让 AI 改了一堆代码后，你连哪里被改了都判断不了。

7.2 我的三条使用体会：什么时候该打断它，什么时候该相信它

第一条，重大项目改动前，先让 Claude Code 给出方案，不要让它直接动手。我习惯用一句话开头：“不要改任何文件，先分析这个项目结构，然后告诉我你打算怎么实现。”它会输出完整思路，等你确认后再说“可以开始改”。这个前置确认步骤，能避免大量无效返工。

第二条，定期用 Git 提交当前状态。Claude Code 改代码可能一次改很多文件，但它的判断不是完美的。每次觉得某个功能接近完成，先在系统里做一次 commit，这样后续出了问题可以随便回滚，不用胆战心惊地试。没有 Git 兜底的情况下，我从不建议在真实项目里尝试一个不熟悉的自动化改动。

第三条，对话上下文过长时，主动用 /clear 开新会话。Claude Code 的上下文窗口虽然很大，但塞得太多时，它对项目新需求的遵循能力会下降。与其让它带着一肚子历史包袱理解新需求，不如直接 /clear，再用两句话说明当前项目状态，让它重新开始。刚开始我总觉得“把所有背景都告诉它才能干得好”，后来发现，上下文干净往往比上下文大更重要。

现在每次在新电脑上装 Claude Code，我基本只需要开一个终端，执行 npm install -g @anthropic-ai/claude-code，再跑一次 claude 登录，五分钟内就能回到工作状态。真正让我留下来的不是安装过程多顺利，而是这个工具在真实项目里那种可被纠正、可被约束、能按项目规矩办事的能力。它住在一个黑色终端窗口里，看起来不够花哨，但把文件改对、把测试跑通、把繁琐工作理出清晰头绪的时候，你会觉得之前那些环境配置折腾都值了。