夜雨聆风什么是 WSL？
WSL 全称 Windows Subsystem for Linux，中文叫“适用于 Linux 的 Windows 子系统”。简单来说，它让你在 Windows 系统里直接运行一个完整的 Linux 环境，不需要安装虚拟机，也不需要给电脑装双系统。
把 WSL 理解成“Windows 内置的 Linux 模拟器”就差不多了：
它像一台电脑里的电脑：你可以在里面运行 Linux 的命令和软件，完全不影响你外面正常使用 Windows。
文件互通：在 WSL 里，你可以通过
/mnt/c/、/mnt/d/这样的路径访问 Windows 的 C 盘、D 盘文件。反过来，Windows 里的文件也都能在 WSL 里编辑和运行。轻量高效：启动速度秒级，占用资源很少，比开一台虚拟机轻便得多。
为什么 Claude Code 需要 WSL？
Claude Code 目前的 Windows 版本存在兼容性问题。如果你直接在 Windows 的 PowerShell 里通过 npm 安装，运行时会报错：指定的可执行文件不是此操作系统平台的有效应用程序。
这是因为 Claude Code 的底层是为 Linux 环境编译的，放在纯 Windows 里无法运行。而 WSL 提供了一个完美的 Linux 环境，让 Claude Code 能正常工作，同时你还能继续用 Windows 上的各种软件（比如 IntelliJ IDEA）。
适用场景
Windows 用户，想安装使用 Claude Code
直接通过 npm 安装遇到
...不是此操作系统平台的有效应用程序错误在线安装 WSL 时遇到网络超时问题
启动 Claude Code 后遇到连接错误或地区限制
第一阶段：离线安装 WSL 系统
⚠️ 常见坑点：执行
wsl --install Ubuntu-24.04时报错WININET_E_TIMEOUT，原因是国内无法稳定连接 GitHub 下载发行版列表。1.1 检查是否已有 WSL
打开 PowerShell，运行：
wsl -l -v
如果显示已安装的发行版（如 Ubuntu），说明 WSL 已就绪，可跳到 1.4 步骤。
如果提示命令不存在，说明需要先启用 WSL 功能。
1.2 启用 WSL 功能（如未启用）
以管理员身份打开 PowerShell，运行：
powershell
wsl --install --no-distribution
执行完成后重启电脑。
1.3 手动下载 Ubuntu WSL 镜像（绕过网络超时）
用浏览器访问 Ubuntu 官方发布页：
text
https://releases.ubuntu.com/noble/
下载文件 ubuntu-24.04.3-wsl-amd64.wsl（版本号可能略有不同，认准 .wsl 后缀即可）。
1.4 离线安装 Ubuntu
以管理员身份打开 PowerShell，执行以下命令（根据实际下载路径修改文件路径）：
powershell
wsl --import Ubuntu-2404 C:\WSL\Ubuntu-2404 "C:\Users\你的用户名\Downloads\ubuntu-24.04.3-wsl-amd64.wsl" --version 2
参数说明：
Ubuntu-2404：安装后在 WSL 中显示的名称（可自定义）C:\WSL\Ubuntu-2404：安装目录（可自定义）--version 2：指定使用 WSL2 版本
1.5 设置默认用户
powershell
Ubuntu-2404 config --default-user 你的用户名
1.6 验证安装
powershell
wsl -l -v
看到 Ubuntu-2404 且 VERSION 显示为 2 即表示成功。
1.7 首次启动与系统更新
在开始菜单找到 Ubuntu-2404 并启动，然后执行：
bash
sudo apt update && sudo apt upgrade -y
💡 忘记设置密码怎么办？
如果首次启动时没设密码就退出了，可以用wsl -u root -d Ubuntu-2404以 root 身份进入，然后运行passwd 你的用户名重新设置密码。
第二阶段：安装 Node.js 环境
2.1 安装 Node.js 20.x LTS 版本
bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
2.2 验证安装
bash
node --version
npm --version
看到版本号即表示安装成功。
第三阶段：安装 Claude Code
⚠️ 常见坑点：直接使用
npm install -g会报EACCES: permission denied权限错误，需要先配置 npm 用户目录。3.1 配置 npm 用户目录（避免权限问题）
bash
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
3.2 安装 Claude Code
bash
npm install -g @anthropic-ai/claude-code
3.3 验证安装
bash
claude --version
正常显示版本号即表示安装成功。
第四阶段：配置 API 中转（解决网络连接问题）
⚠️ 常见坑点：启动 Claude Code 后出现
ERR_BAD_REQUEST或地区限制提示，原因是国内无法直接访问 Anthropic 官方 API。4.1 获取中转 API Key
注册一个 API 中转服务（如 AnyRouter https://anyrouter.top 或灵芽 https://api.lingyaai.cn），获取以 sk- 开头的 API 密钥。
4.2 配置中转地址
创建并编辑配置文件：
bash
mkdir -p ~/.claude
nano ~/.claude/settings.json
填入以下内容（务必替换为实际值）：
json
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "sk-你的API密钥",
"ANTHROPIC_BASE_URL": "https://你的中转地址"
}
}
保存退出：按 Ctrl+X，然后按 Y，最后按 Enter。
4.3 验证配置
bash
claude
出现欢迎界面并能正常对话即表示成功。
💡 模型不支持怎么办？
如果提示model claude-sonnet-4-6 is not supported，需要在settings.json中添加一行：
text
"ANTHROPIC_DEFAULT_SONNET_MODEL": "中转服务支持的模型ID"
第五阶段：与 IntelliJ IDEA 配合使用
5.1 在 WSL 中访问 Windows 上的 Java 项目
WSL 会自动挂载 Windows 的盘符，格式为 /mnt/盘符/。
bash
# 假设你的 IDEA 项目在 E:\ideawookspace\jiankang
cd /mnt/e/ideawookspace/jiankang
5.2 在 IDEA 内置终端中使用 Claude Code
打开 IDEA 底部的 Terminal 标签页
点击终端右上角的 ∨ 箭头，选择 Ubuntu-2404（或你设置的名称）
在项目目录下直接运行：
bash
claude
5.3 从 Windows 直接启动（快捷方式）
powershell
# 直接启动
wsl -d Ubuntu-2404 claude
# 指定项目目录启动
wsl -d Ubuntu-2404 claude --cd /mnt/e/ideawookspace/jiankang
---
第六阶段：常用命令速查
第七阶段：问题排查速查表
✅ 安装成功标志
当你在 WSL 终端输入 claude 后，看到以下界面即表示完全成功：
text
Welcome to Claude Code v2.1.114
* █████▓▓░
* ███▓░ ░░
░░░░░░ ███▓░
░░░ ░░░░░░░░░░ ███▓░
░░░░░░░░░░░░░░░░░░░ * ██▓░░ ▓
░▓▓███▓▓░
❯
---
这份教程覆盖了从零到成功的完整流程，以及所有常见的坑点和解决方法。如果后续使用中还有其他问题，随时可以再来问我！
