AI Agent / 系统课时
在 Windows 上安装
在 Windows 上安装
在 Windows 上使用 Claude Code,关键不是只把命令装上,而是先决定使用原生 Windows + Git Bash,还是 WSL 2。两条路线的文件路径、Shell 和工具链不同;选定一条并保持项目、终端和 Claude Code 在同一环境,能避开大多数路径问题。
学习目标
- 根据项目工具链选择原生 Windows + Git Bash 或 WSL 2
- 完成安装并用版本和诊断命令确认 Claude Code 可用
- 识别 Windows、Git Bash 与 WSL 路径混用导致的常见故障
先选运行环境
原生 Windows 适合依赖 Windows SDK、PowerShell 或本机工具的项目。Git for Windows 目前不是启动 Claude Code 的硬性依赖,但安装后可提供 Git Bash,让 Bash 脚本和常见 Unix 命令更顺手。WSL 2 更适合 Linux 工具链,并支持 Claude Code 的 Linux 沙箱能力;WSL 1 可运行,但不支持该沙箱。
这两条路线不要混装后交叉启动。同一个项目最好固定由一侧负责:原生路线从 PowerShell、CMD 或 Git Bash 启动;WSL 路线则在 WSL 发行版中安装并运行 claude。
使用原生 Windows 与 Git Bash
先确认 Git Bash 的默认可执行文件存在。若 Git 安装在自定义目录,把路径替换成实际位置。
Test-Path 'C:\Program Files\Git\bin\bash.exe'预期输出
True然后在普通 PowerShell 中运行官方原生安装器,不需要管理员权限:
irm https://claude.ai/install.ps1 | iex
claude --version预期输出
<INSTALLER_OUTPUT>
<VERSION> (Claude Code)安装器的具体提示会随版本变化;关键是安装过程无错误,并且 claude --version 能打印版本号。若 Claude Code 没有找到 Git Bash,可在 %USERPROFILE%\.claude\settings.json 指定路径:
{
"env": {
"CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
}
}该配置会让 Claude Code 使用指定的 Git Bash。保存后重新启动终端,再检查安装与设置:
claude doctor预期输出
<DIAGNOSTIC_OUTPUT>诊断字段会随版本变化;验收点是没有安装失败、设置文件无效或 Shell 路径错误。若仍报告路径问题,先确认文件实际存在,而不是继续叠加多个 PATH 配置。
使用 WSL 2
先在 PowerShell 确认发行版运行在 WSL 2。不同语言版本的 Windows 输出文字可能不同,重点看最后一列版本号为 2。
wsl -l -v预期输出
NAME STATE VERSION
* <WSL_DISTRO> <STATE> 2进入该 WSL 发行版后,使用 Linux 安装命令,并在同一个 WSL 终端中验证:
curl -fsSL https://claude.ai/install.sh | bash
claude --version预期输出
<INSTALLER_OUTPUT>
<VERSION> (Claude Code)WSL 路线中的 claude 应该是 Linux 侧安装,不要从 PowerShell 调用它再让它跨回 WSL。可继续确认命令实际来自 Linux 用户目录:
which claude预期输出
/home/<USER>/.local/bin/claude若结果落在 /mnt/c/...,说明当前 WSL 环境解析到了 Windows 侧程序,应先修正 PATH 或重新安装 Linux 侧 Claude Code。
处理路径混用
同一个 Windows 文件在不同 Shell 中写法不同:PowerShell 使用 C:\Users\<USER>\project,Git Bash 常写成 /c/Users/<USER>/project,WSL 则写成 /mnt/c/Users/<USER>/project。配置文件需要哪种形式,取决于真正读取它的进程,而不是你眼前正在使用的终端。
在 WSL 中做 Linux 项目时,优先把仓库放在 /home/<USER>/...,避免长期从 /mnt/c/... 跨文件系统搜索大量文件。若 which claude、Git、包管理器或编译器解析到了另一侧的路径,先修正环境边界,再处理 Claude Code 本身。
安装完成后的验收标准很简单:从你选定的环境进入真实项目目录,版本检查可用,诊断不报告安装或设置错误,并且项目路径在同一套 Shell 语义下可读写。做到这三点,后续的认证和项目操作才不会被 Windows/WSL 路径差异反复干扰。