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

目录

• 一、先决定你走哪条路：原生 Windows 还是 WSL？
• 方案 A：原生 Windows
• 方案 B：WSL
• 二、推荐的新手默认组合
• 三、先打开正确的终端：PowerShell
• 四、检查winget能不能用
• 五、安装 Git
• 六、安装 Node.js 和 npm
• 七、安装 Claude Code
• 八、为什么 Windows 上最容易出现“安装成功但命令不存在”？
• 第一步：看 npm 全局前缀
• 第二步：先彻底重开终端
• 第三步：检查 PATH
• 九、环境变量到底该怎么在 Windows 上配？
• 十、PowerShell、cmd、Git Bash、WSL 到底有什么区别？
• 十一、如果你想走 WSL，正确姿势是什么？
• 十二、如何确认你的 Windows 环境真的打通了？
• 十三、Windows 上最常见的 7 类问题和修法
• 十四、给新手的 Windows 最稳妥方案
• FAQ
• 结语

如果说 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 Terminal
• PowerShell
• Git for Windows
• Node.js for Windows
• npm 全局安装 Claude Code

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

使用：

• 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

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

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

先打开：

• Windows Terminal
• PowerShell 标签页

检查 PowerShell 版本：

$PSVersionTable.PSVersion

如果这一步正常，就用同一个 PowerShell 窗口完成后面的安装和验证。

现代 Windows 上，用 winget 装 Git 和 Node 最省心。

winget --version

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

如果不行：

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

先检查：

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 "you@example.com"

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 冲突。

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

where.exe claude
claude --version

如果没有，再执行：

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

安装后再验证：

where.exe claude
claude --version

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 config get prefix

再看全局包：

npm list -g --depth=0

也可以查 PowerShell 是否能识别：

Get-Command claude -ErrorAction SilentlyContinue

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

查看用户级 PATH：

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

查看系统级 PATH：

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

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

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 行为

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

环境	新手建议	说明
PowerShell	推荐	Windows 原生支持最好
cmd	可用但不推荐	功能偏基础
Git Bash	能用但不建议新手首选	多一层 shell 差异
WSL	适合进阶用户	更像 Linux，但要单独维护环境

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

WSL 是另一套环境：

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

先检查 WSL 状态：

wsl --status

如果还没装：

wsl --install

然后按系统提示重启。

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

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

不要以为 Windows 侧装好的 Node/npm 会自动覆盖 WSL。

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

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 执行低风险操作。

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
• 杀毒软件
• 企业安全终端
• 是否把刚安装的可执行文件隔离了

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

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

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

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下Claude Code的安装教程与常见问题全排查的详细内容，更多关于Claude Code 安装的资料请关注风君子博客其它相关文章！