Claude Code | Windows 安装避坑指南

本文由 QClaw 自己边尝试边写的，不是我写的！但是最终安装成功~

作者：Codex 日期：2026-04-20 环境：Windows 10/11 x64，Node.js v22 + npm v10，已开启代理，沙箱隔离已关闭

一、环境检测

在开始之前，先确认当前系统已具备安装 Claude Code 的前置条件：

当前环境状态

OS: Windows Build 10.0.26100 (x64)
Shell: PowerShell 5.1+
Node.js: v22.16.0
npm: 10.9.8
Git: 已安装 (C:\Program Files\Git\cmd\git.exe)

网络连通性检测

💡 提示：如果你在大陆，需要先配置代理（VPN/Clash 等），确保能访问 npm registry 和 GitHub。

二、安装步骤

方法一：npm 全局安装（推荐）

这是最简单、最直接的方式，只需要一个命令：

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

详细操作

1. 打开 PowerShell（Win+X → Windows PowerShell 或终端）
2. 检查 Node.js 和 npm 版本（确保满足要求）

node --version   # 应显示 v18.0.0 或更高
npm --version    # 应显示 9.0.0 或更高

1. 执行安装命令

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

预期输出示例：

added 2 packages in 2m

⚠️ 如果遇到 EACCES 权限错误（Linux/macOS），需要加 sudo，Windows 通常不需要：

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

1. 查看安装路径

npm config get prefix

输出：C:\Users\用户名\AppData\Roaming\QClaw\npm-global

1. 确认文件存在

Get-ChildItem "C:\Users\用户名\AppData\Roaming\QClaw\npm-global"

应有以下文件：

• claude.cmd（Windows 命令行入口）
• claude（Linux/macOS 脚本）
• claude.ps1（PowerShell 脚本）
• node_modules\（依赖目录）

方法二：npx 免安装运行

不想全局安装？可以用 npx 直接运行（每次会自动下载最新版本）：

npx @anthropic-ai/claude-code --version

⚠️ 每次运行都会重新下载，速度较慢，仅适合临时尝鲜。

方法三：Scoop 安装

如果你使用 Scoop 作为包管理器：

scoop install claude-code

⚠️ 注意：Scoop 官方仓库中的 Claude Code 包可能不是最新版，推荐使用 npm 安装。

方法四：手动下载（备选）

1. 访问 GitHub releases 页面： https://github.com/anthropics/claude-code/releases
2. 下载对应平台的二进制文件（Windows → .zip）
3. 解压到任意目录（如 C:\Program Files\Claude Code\）
4. 将该目录添加到 PATH 环境变量

三、安装过程文字记录

步骤 1：环境快照

安装前的系统状态：

=== 系统环境快照 ===
OS: Windows Build 10.0.26100 (x64)

--- 包管理器 ---
winget: 已安装
choco: 已安装

--- 基础运行时 ---
node: v22.16.0
npm: 10.9.8
python: Python 3.8.6

--- CLI 工具 ---
git: 已安装
curl.exe: 已安装
claude: 未安装 ← 安装目标

步骤 2：执行安装命令

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

安装进行中：

• npm 向 registry.npmjs.org 请求包信息
• 下载 @anthropic-ai/claude-code 及依赖（实际只新增 2 个包）
• 安装到全局目录

步骤 3：安装完成

added 2 packages in 2m

步骤 4：确认文件已生成

Get-ChildItem "C:\Users\用户名\AppData\Roaming\QClaw\npm-global"

输出：

目录: C:\Users\用户名\AppData\Roaming\QClaw\npm-global

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----         2026/4/20     11:11                node_modules
-a----         2026/4/20     11:13            308 claude
-a----         2026/4/20     11:13            160 claude.cmd
-a----         2026/4/20     11:13            520 claude.ps1

步骤 5：验证安装

$ claude --version
2.1.114 (Claude Code)

$ where.exe claude
C:\Users\用户名\AppData\Roaming\QClaw\npm-global\claude
C:\Users\用户名\AppData\Roaming\QClaw\npm-global\claude.cmd

四、遇到的问题与解决方案

问题 1：网络超时

错误信息：

npm ERR! network request to https://registry.npmjs.org/ failed

原因： 网络无法访问 npm registry（通常是大陆网络问题）。

解决方案：

1. 确保已开启代理/VPN
2. 或配置 npm 国内镜像：npm config set registry https://registry.npmmirror.com

问题 2：权限不足

错误信息（Linux/macOS）：

npm ERR! Error: EACCES: permission denied

解决方案：

• Linux/macOS 使用 sudo：sudo npm install -g @anthropic-ai/claude-code
• 或配置 npm 全局目录到用户目录：mkdir ~/.npm-global npm config set prefix '~/.npm-global' export PATH=~/.npm-global/bin:$PATH

问题 3：安装成功，但 PowerShell 找不到 claude 命令 ⭐重点

错误信息：

PS C:\Users\worable> claude --version
claude : 无法将"claude"项识别为 cmdlet、函数、脚本文件或可运行程序的名称。
请检查名称的拼写，如果包括路径，请确保路径正确，然后再试一次。

排查步骤

第一步：确认文件确实存在

Test-Path "C:\Users\用户名\AppData\Roaming\QClaw\npm-global\claude.cmd"

返回 True 说明文件在，只是找不到。

第二步：确认 PATH 中是否包含 npm-global

$env:Path -split ';' | Where-Object { $_ -like '*npm-global*' }

• 如果有输出：PATH 里能找到目录 → 可能是 session 问题（见"解法一"）
• 如果没有输出：PATH 里没有目录 → 才是真正缺 PATH（见"解法二"）

第三步：用完整路径直接运行验证可用性

& "C:\Users\用户名\AppData\Roaming\QClaw\npm-global\claude.cmd" --version

如果返回 2.1.114 (Claude Code)，说明安装完全正常，只是 PATH 配置问题。

根因分析：QClaw 运行时 vs 系统 PATH

这是最容易踩的坑，需要理解 Windows PATH 的两层机制：

npm 全局安装时，不会自动写入系统 PATH。npm install -g 只是把文件放到全局目录，但不会改系统设置。

所以：

• 如果你用的是 QClaw 内部运行的 PowerShell（QClaw 启动时注入了 PATH）→ 当前窗口能找到 claude
• 如果你打开了一个新的独立 PowerShell 窗口 → 系统 PATH 里没有 npm-global → 找不到 claude

解法一：刷新当前 session 的 PATH（仅修复当前窗口）

适用于：PATH 里其实有 npm-global，但安装过程中 PATH 变了导致缓存过期。

$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

然后验证：

claude --version

⚠️ 注意：这个命令只能修复当前窗口。关掉再开新窗口，又会失效。只适合临时调试用。

解法二：一键永久写入系统 PATH ✅推荐

适用于：系统 PATH 里本来就没有 npm-global（第一次安装 npm 全局工具）。

只需执行一次，之后所有 PowerShell 窗口都自动生效：

$npmGlobal = "C:\Users\用户名\AppData\Roaming\QClaw\npm-global"
$userPath = [System.Environment]::GetEnvironmentVariable("Path", "User")
if ($userPath -notlike "*npm-global*") {
    [System.Environment]::SetEnvironmentVariable("Path", $userPath + ";$npmGlobal", "User")
    Write-Host "已写入系统 PATH！新开 PowerShell 窗口后生效。" -ForegroundColor Green
} else {
    Write-Host "PATH 中已有 npm-global，无需重复写入。" -ForegroundColor Yellow
}

验证（需要新开 PowerShell 窗口）：

# 关掉当前窗口，重新打开一个新的，执行：
claude --version

预期输出：

2.1.114 (Claude Code)

解法三：图形界面手动添加（适合不想敲命令的人）

1. 按 Win + R，输入 sysdm.cpl，回车
2. 点 高级 → 环境变量
3. 在 用户变量 里找到 Path，双击编辑
4. 点 新建，粘贴以下路径：C:\Users\用户名\AppData\Roaming\QClaw\npm-global
5. 确定 → 确定 → 确定
6. 重新打开 PowerShell 窗口

问题 4：版本过旧

错误信息：

claude --version
2.0.x  (旧版本)

解决方案： 升级到最新版：

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

问题 5：QClaw 环境下 PATH 有 npm-global，但独立 PowerShell 没有

这是 QClaw 用户特有的情况。因为 QClaw 的运行时在启动时会注入自己的 npm-global 路径到当前进程 PATH，但这不会持久化到系统 PATH。

症状：

• QClaw 控制的终端里 claude 命令正常
• 自己手动打开的 PowerShell 窗口找不到命令

解决：见问题 3 的"解法二"，执行一次永久写入即可。

五、快速入门

1. 基本用法

# 在当前目录启动 Claude Code（交互模式）
claude

# 在指定目录启动
claude /path/to/project

# 直接执行一条命令（不进入交互模式）
claude "解释这段代码的作用"

2. 首次使用配置

首次运行 claude 时，会提示你：

• 登录 Anthropic 账号（API Key 登录）
• 配置编辑器偏好
• 允许发送匿名遥测数据

# 登录（使用 API Key）
claude login

# 登出
claude logout

# 查看当前配置
claude config list

3. 常用命令

六、环境依赖一览

安装 Claude Code 所需的最小环境：

底层依赖（必须）：
  Node.js ≥ 18.0.0
  npm ≥ 9.0.0

可选依赖：
  Git（用于代码仓库功能）
  网络代理（大陆用户必备）

不需要（Claude Code 内置）：
  Python
  Go
  其他运行时

七、完整安装记录

=== 完整安装日志 ===

[安装前]
node: v22.16.0
npm: 10.9.8
claude: 未安装

[执行命令]
npm install -g @anthropic-ai/claude-code

[安装中]
added 2 packages in 2m

[安装后]
claude: 2.1.114 (Claude Code)
安装路径: C:\Users\用户名\AppData\Roaming\QClaw\npm-global\
可执行文件:
  - claude.cmd (308 bytes, Windows 入口)
  - claude.exe (245 MB, Node.js bundled binary)
  - claude.ps1 (520 bytes, PowerShell wrapper)

[PATH 问题排查]
问题: 新 PowerShell 窗口找不到 claude 命令
原因: npm 全局目录未写入系统 PATH
根因: QClaw 注入的 PATH 只在 QClaw session 中生效，不持久化
解决: 执行 SetEnvironmentVariable 永久写入 User PATH
结果: ✅ 所有新窗口均可正常使用 claude

[最终状态]
✅ npm install 完成
✅ claude.cmd 文件存在
✅ PATH 已永久写入
✅ claude 命令全局可用

八、常见问题 FAQ

Q：Claude Code 和 Claude CLI 是一样的吗？ A：是的，Claude Code 是 Anthropic 官方提供的命令行工具。

Q：需要付费吗？ A：基础功能免费，但需要消耗 Anthropic API 额度。Claude Code 使用 Claude Sonnet 4 模型，每 1000 次调用约 $3。

Q：安装后在哪里写代码？ A：Claude Code 会在你的终端里运行，用自然语言对话式操作代码文件。推荐搭配 VS Code 使用。

Q：能否在 Docker/WSL 里运行？ A：可以，但性能和体验最佳的是在本机 Windows/macOS/Linux 原生运行。

Q：如何卸载？

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

Q：PATH 问题怎么判断是 session 级别还是系统级别？ A：运行 $env:Path -split ';' | Where-Object { $_ -like '*npm-global*' }，有输出说明 session 有，没有说明系统也没有。对应使用"解法一"或"解法二"。

九、错误速查表

教程制作：Codex · 2026-04-20 · 含完整 PATH 问题排查记录