Windows下Claude Code的安装教程与常见问题全排查实践整理

平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“Windows下Claude Code的安装教程与常见问题全排查”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际使用顺序，把思路、关键写法和容易踩坑的地方讲清楚，方便你直接对照操作。

理解这一步时，如果说 Mac 上安装 Claude Code 的难点在 PATH 和 shell 设置，那么 Windows 上的难点通常是：环境太多，路径太多，入口太多。

你可能同时接触到：

• PowerShell
• Windows Terminal
• 命令提示符（cmd）
• Git Bash
• WSL
• winget
• 手动安装版 Node.js
• 手动安装版 Git

结果就是：

• 你在一个终端里能运行 claude
• 换一个终端就不行了
• 变量在 PowerShell 里有，在 WSL 里没有
• Git 装好了，但 PATH 没刷新
• npm 全局安装成功了，但系统说命令不存在

所以 Windows 版最重要的不是快，而是先统一环境，再安装，再验证。

一、先决定你走哪条路：原生 Windows 还是 WSL？

这是第一步，否则后面很容易越装越乱。

方案 A：原生 Windows

采用：

• Windows Terminal
• PowerShell
• Git for Windows
• Node.js for Windows
• npm 全局安装 Claude Code

这个方案最适合大多数新手。

方案 B：WSL

采用：

• WSL2
• Ubuntu / Debian
• 在 Linux 子系统里安装 Git、Node、Claude Code

落到代码里，这个方案长期更像真正的 Linux 开发环境，但对完全新手来说，会多一层理解成本。

落到代码里，若你是第一次装，我建议先走原生 Windows + PowerShell。

二、建议的新手默认组合

最稳妥的组合是：

• Windows 10/11 最新更新
• Windows Terminal
• PowerShell
• winget
• Git for Windows
• Node.js LTS
• Claude Code via npm

这套方案最无聊，也最稳定。

三、先打开正确的终端：PowerShell

尽量不要一上来就在多个 shell 之间来回切换。

先打开：

• Windows Terminal
• PowerShell 标签页

检查 PowerShell 版本：

$PSVersionTable.PSVersion

结合项目来看，若这一步正常，就用同一个 PowerShell 窗口完成后面的安装和验证。

四、检查winget能不能用

结合项目来看，现代 Windows 上，用 winget 装 Git 和 Node 最省心。

winget --version

若命令正常，说明你可以直接用系统包管理方式安装。

如果不行：

• 更新 Microsoft Store 里的 App Installer
• 或者改走手动下载安装包

五、安装 Git

先检查：

git --version

如果没有，就安装：

winget install --id Git.Git -e --source winget

安装完成后，一定要关闭并重新打开 PowerShell。

再验证：

git --version
where.exe git

为什么 Claude Code 新手必须尽快补上 Git？

因为后面所有真正有用的工作流都离不开它：

• 跟踪改动
• 查看 diff
• 管理分支
• 撤销修改
• 让项目具备标准开发上下文

若你现在只是一个空文件夹，建议顺手初始化仓库：

mkdir $HOMEProjectsclaude-code-test -Force
cd $HOMEProjectsclaude-code-test
git init

再设置一下身份：

git config --global user.name "你的名字"
git config --global user.email "[email protected]"

六、安装 Node.js 和 npm

落到代码里，Claude Code 常用安装方式依赖 npm，所以 Node.js/npm 要先通。

先检查：

node --version
npm --version

若没有，就安装 Node.js LTS：

winget install --id OpenJS.NodeJS.LTS -e --source winget

安装完成后，关闭 PowerShell，再打开一个新的。

再次检查：

node --version
npm --version
where.exe node
where.exe npm

如果 node 能运行但 npm 不正常，说明安装可能不完整，或者系统里有旧版 Node 冲突。

七、安装 Claude Code

先看系统是否已经安装过：

where.exe claude
claude --version

如果没有，再执行：

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

安装后再验证：

where.exe claude
claude --version

八、为什么 Windows 上最容易出现“安装成功但命令不存在”？

Windows 用户最常用的报错之一就是：

claude : The term 'claude' is not recognized as the name of a cmdlet, function, script file, or operable program.

通常不是因为 Claude Code 没装上，而是因为：

• npm 全局安装目录没进 PATH
• 安装后当前 PowerShell 没刷新
• 你在一个 shell 里装，去另一个 shell 里测
• 系统有多个 Node/npm 版本互相冲突

第一步：看 npm 全局前缀

npm config get prefix

再看全局包：

npm list -g --depth=0

也可以查 PowerShell 是否能识别：

Get-Command claude -ErrorAction SilentlyContinue

第二步：先彻底重开终端

很多 PATH 问题其实不是设置错了，而是 shell 还在用旧环境。

第三步：检查 PATH

查看用户级 PATH：

[Environment]::GetEnvironmentVariable("Path", "User")

查看系统级 PATH：

[Environment]::GetEnvironmentVariable("Path", "Machine")

若 npm 全局可执行文件所在目录不在 PATH 里，就要补进去。

九、环境变量到底该怎么在 Windows 上配？

Windows 新手最容易混淆的一点是：当前会话变量和持久变量不是一回事。

当前 PowerShell 会话内临时设置

$env:ANTHROPIC_API_KEY = "your_key_here"
$env:OPENAI_API_KEY = "your_crazyrouter_key"
$env:OPENAI_BASE_URL = "https://crazyrouter.com/v1"

这类变量只在当前窗口有效，关掉就没了。

持久化到当前用户环境变量

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "your_key_here", "User")
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "your_crazyrouter_key", "User")
[Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", "https://crazyrouter.com/v1", "User")

设置完后，关闭 PowerShell，再开一个新窗口验证：

echo $env:ANTHROPIC_API_KEY
echo $env:OPENAI_API_KEY
echo $env:OPENAI_BASE_URL

为什么我在 PowerShell 能看到变量，在别的终端里看不到？

因为不同环境并不共享同一套会话状态。

• PowerShell 会话变量 ≠ cmd 会话变量
• Windows 原生环境变量 ≠ WSL 内部 shell 变量
• Git Bash 也有自己的一层 shell 行为

十、PowerShell、cmd、Git Bash、WSL 到底有什么区别？

这一步很重要，因为很多 Windows 新手在这里越装越乱。

结合项目来看，如果你是在 PowerShell 里装的 Node 和 Claude Code，不要立刻切到 WSL 里测试，同时假设一切都会自动同步。

WSL 是另一套环境：

• 另一套 PATH
• 另一套包管理器
• 另一套 shell 设置文件
• 另一套环境变量

十一、如果你想走 WSL，正确姿势是什么？

先检查 WSL 状态：

wsl --status

如果还没装：

wsl --install

然后按系统提示重启。

进入 Ubuntu 之后，要把它当成一台 Linux 机器单独设置：

• 在 WSL 里安装 Git
• 在 WSL 里安装 Node
• 在 WSL 里安装 Claude Code
• 在 WSL 的 ~/.bashrc / ~/.zshrc 里设置环境变量

结合项目来看，不要以为 Windows 侧装好的 Node/npm 会自动覆盖 WSL。

十二、如何确认你的 Windows 环境真的打通了？

建议至少执行接下来这一组检查：

git --version
node --version
npm --version
claude --version
where.exe git
where.exe node
where.exe npm
where.exe claude

然后再新建一个测试目录：

mkdir $HOMEProjectsclaude-code-test -Force
cd $HOMEProjectsclaude-code-test
if (-not (Test-Path .git)) { git init }
"# test" | Out-File README.md -Encoding utf8

之后再让 Claude Code 执行低风险操作。

十三、Windows 上最常用的 7 类问题和修法

1）claude不是内部或外部命令 / not recognized

原因：

• npm 全局可执行目录没进 PATH
• 终端没刷新
• 安装没真正完成

处理：

• 重新打开 PowerShell
• 检查 npm config get prefix
• 检查 npm list -g --depth=0
• 检查 Get-Command claude

2）Git 装好了，但 PowerShell 还是找不到

原因：

• 你安装前就打开了这个终端，PATH 没更新

处理：

• 完整关闭终端
• 重新打开
• 用 where.exe git 验证

3）Node 有了，但 npm 不正常

原因：

• 安装不完整
• 系统里存在冲突版本

处理：

• 重新安装 LTS 版本
• 必要时卸掉冲突旧版再装
• 同时验证 node --version 和 npm --version

4）环境变量只在当前窗口有效

原因：

• 只用了 $env:...，没做持久化

处理：

• 用 [Environment]::SetEnvironmentVariable(..., "User")
• 然后重开终端

5）PowerShell 能用，WSL 不能用；或者反过来

原因：

• 你其实在维护两套完全不同的环境

处理：

• 明确选一个主环境
• 在那个环境里把全部依赖补齐

6）公司网络或代理导致 npm 安装失败

可能需：

npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

7）安全软件拦截 CLI 或脚本

若日志看起来正常，但命令行为不正常，要检查：

• Windows Security
• 杀毒软件
• 企业安全终端
• 是否把刚安装的可执行文件隔离了

十四、给新手的 Windows 最稳妥方案

如果你的目标只有一个：尽快把 Claude Code 稳定跑起来，那我建议：

• Windows Terminal
• PowerShell
• winget
• Git for Windows
• Node.js LTS
• npm 全局安装 Claude Code
• 用户级持久环境变量

这套方案最适合写教程，也最适合给别人远程排查。

FAQ

Q1：新手应该直接用 PowerShell 还是 WSL？

落到代码里，若你是第一次配，先用 PowerShell。你已经熟悉 Linux 开发环境，再考虑 WSL。

Q2：为什么明明 npm 显示安装成功，claude还是不能用？

结合项目来看，通常是 PATH 没刷新、装到了你当前 shell 不可见的位置，或者你在不同终端之间切来切去导致判断混乱。

Q3：Windows 上一定要先装 Git 吗？

在这个场景下，从实际工作流看，几乎可以视为必须。没有 Git，后面很多正常开发动作都会很别扭。

Q4：环境变量应该存在哪里？

结合项目来看，若你希望重开终端后还有效，就应该设置成 用户级持久环境变量，而不是只写当前 PowerShell 会话。

Q5：Git Bash 适不适合跑 Claude Code？

落到代码里，能跑，但不适合新手拿它当第一环境。因为它会多引入一层 shell 差异，排错更复杂。

结语

理解这一步时，Windows 上安装 Claude Code 不难，难的是你可能不知不觉同时踩进了两三套环境里。

只要你把顺序固定下来：

1. Windows Terminal
2. PowerShell
3. winget
4. Git
5. Node/npm
6. Claude Code
7. PATH
8. 环境变量
9. Git 仓库验证

落到代码里，总的来说，windows这部分内容适合结合实际项目边做边理解。先抓住核心思路，再逐步补上细节和边界处理，最后效果会更稳定，也更容易复用。