WSL2 安装 Claude Code 全攻略

本文详细介绍如何在 WSL2 中从零开始安装配置 Claude Code，并接入 MiniMax Coding Plan 实现国内访问

一、前置知识

1.1 什么是 WSL2

WSL2（Windows Subsystem for Linux 2）是 Windows 10/11 自带的轻量级 Linux 虚拟机，与传统虚拟机相比：

1.2 Git Bash 与 WSL2 的区别

很多初学者容易混淆这两种环境：

# Git Bash (MINGW64) - Windows 上的轻量级 Linux 环境
MINGW64_NT-10.0-22000  # 实际是 Windows 程序

# WSL2 - 真正的 Linux 虚拟机
Linux version 5.x.xmicrosoft-standard-WSL2

关键区别：

• Git Bash：Windows 上的模拟层，兼容性有限
• WSL2：完整的 Linux 内核，真正可信赖的开发环境

1.3 环境要求

• Windows 10 版本 2004+ 或 Windows 11
• Node.js 18+ 版本
• WSL2 已启用

二、核心概念

2.1 Claude Code

Claude Code 是 Anthropic 推出的 AI 编程助手，支持：

• 代码生成与编辑
• Git 操作自动化
• 项目理解与分析
• 多轮对话交互

2.2 WSL2 网络机制

WSL2 有独立的网络栈，访问原理如下：

graph LR
    A[Windows 浏览器] -->|127.0.0.1:8100| B{网络请求}
    B -->|服务监听 0.0.0.0| C[WSL2 虚拟机]
    C -->|Laravel| D[php artisan serve]
    C -->|Vite| E[npm run dev]

核心要点：WSL2 中运行的服务必须监听 0.0.0.0（所有网络接口），Windows 才能通过 127.0.0.1 访问。

2.3 WSL2 与 Windows 文件互访

WSL2 访问 Windows 文件
├── 方式一：/mnt/<盘号>/路径
│   示例：/mnt/d/web/<项目名>
│
└── 方式二：\\wsl$<名称>\路径
    示例：\\wsl$\Ubuntu\home\用户名

Windows 访问 WSL2 文件
└── 方式：\\wsl$<名称>\路径
    示例：\\wsl$\Ubuntu\home\<用户名>\.claude\

三、实现步骤

3.1 检查当前环境

首先确认你是在 WSL2 环境中：

# 检查是否为 WSL2
cat /proc/version
# 输出应包含 "microsoft" 或 "WSL2"

# 检查 Node.js 版本
node -v
# 要求：18.0.0 或更高

# 检查 npm 版本
npm -v

# 检查当前用户名
whoami

3.2 启用 WSL2（如果未启用）

在 Windows PowerShell 中以管理员身份运行：

# 启用 WSL2 功能
wsl --install

# 重启电脑后生效

3.3 安装 Node.js（如果未安装）

WSL2 中安装 Node.js：

# 方法一：使用 NodeSource 仓库（推荐）
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo bash -
sudo apt-get install -y nodejs

# 方法二：使用 apt
sudo apt update
sudo apt install nodejs npm

# 验证安装
node -v
npm -v

node安装成功

3.4 安装 Claude Code

# 全局安装 Claude Code
sudo npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

claude code安装成功

3.5 配置 Claude Code

3.5.1 创建配置目录

# 确保配置目录存在
mkdir -p ~/.claude

# 查看配置目录
ls -la ~/.claude/

3.5.2 配置 MiniMax Coding Plan

编辑 ~/.claude/settings.json：

{
  "autoUpdatesChannel": "latest",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "你的_MiniMax_API_Token",
    "ANTHROPIC_MODEL": "MiniMax-M2.7",
    "ANTHROPIC_SMALL_FAST_MODEL": "MiniMax-M2.7",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "MiniMax-M2.7",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "MiniMax-M2.7"
  }
}

3.5.3 跳过登录向导

编辑 ~/.claude/.claude.json：

{
  "hasCompletedOnboarding": true
}

3.6 WSL2 与 Windows 配置目录映射

3.6.1 理解目录映射机制

WSL2 的 HOME 目录默认在 Linux 文件系统中：

WSL2 HOME: /home/<用户名>/
Windows 可访问: \\wsl$\Ubuntu-24.04\home\<用户名>\   （每个人的目录名可能不一样，具体以自己的为准，像我就是Ubuntu-24.04）

但很多用户的 WSL2 HOME 被配置为 Windows 路径，此时会出现类似情况：

# 查看 HOME 环境变量
echo $HOME
# 输出可能是：/c/Users/<用户名> （指向 Windows 用户目录）

# 这意味着配置目录与 Windows 共享
~/.claude/  →  C:\Users\<用户名>\.claude\

3.6.2 推荐的目录映射方案

方案一：配置映射到 Windows 可访问路径（推荐）

如果你的 WSL2 项目放在 Windows 文件系统中：

# Windows D盘的项目在 WSL2 中挂载为
/mnt/d/web/<项目名>

# 或者配置 WSL2 自动挂载
# 在 /etc/wsl.conf 中添加：
#[automount]
#enabled = true
#mountGen = true

方案二：保持 WSL2 独立 HOME

如果你希望 WSL2 配置与 Windows 隔离，需要：

1. 修改 WSL2 的 HOME 环境变量：

# 在 ~/.bashrc 中添加
export HOME=/home/<用户名>

# 然后重新加载
source ~/.bashrc

2. 移动配置目录：

# 创建真正的 WSL2 HOME 目录
sudo mkdir -p /home/<用户名>
sudo chown <用户名>: /home/<用户名>

# 移动配置
mv ~/.claude /home/<用户名>/claude_backup

# 验证
ls -la /home/<用户名>/

3.7 验证配置

# 查看配置文件
cat ~/.claude/settings.json
cat ~/.claude/.claude.json

# 测试 Claude Code 启动
cd /mnt/d/web/<项目名>  # 进入项目目录
claude --version

3.8 WSL2 中运行 Laravel 开发服务器

# 进入项目目录
cd /mnt/d/web/<项目名>

# 启动 Laravel 开发服务器（必须指定 --host=0.0.0.0）
php artisan serve --host=0.0.0.0 --port=8100

# 新开终端窗口，启动 Vite
npm run dev -- --host=0.0.0.0

然后在 Windows 浏览器 中访问：

http://127.0.0.1:8100

四、常见问题

4.1 Windows 无法访问 WSL2 中的服务

问题原因：服务监听了 127.0.0.1 或 localhost

解决方案：启动服务时添加 --host=0.0.0.0

php artisan serve --host=0.0.0.0 --port=8100
npm run dev -- --host=0.0.0.0

4.2 WSL2 内存占用过高

创建 C:\Users\<用户名>\.wslconfig 文件：

[wsl2]
memory=4GB
processors=4

然后重启 WSL2：

wsl --shutdown

4.3 换行符问题

Git Bash/WSL2 使用 LF，Windows 使用 CRLF。建议配置 Git：

git config --global core.autocrlf input

4.4 两个环境都装了 Claude Code？

完全正常，可以共存：

五、总结要点

5.1 安装流程回顾

graph TD
    A[检查环境] --> B[安装 Node.js]
    B --> C[安装 Claude Code]
    C --> D[配置 MiniMax API]
    D --> E[验证安装]
    E --> F[启动开发服务]

5.2 核心知识点

1. WSL2 是真正的 Linux 虚拟机，与 Git Bash 有本质区别
2. 服务必须监听 0.0.0.0，Windows 才能通过 127.0.0.1 访问
3. 配置目录可以共享，也可以隔离，取决于你的使用习惯
4. WSL2 内存动态分配，不用时自动释放
5. 关闭终端不等于关闭 WSL2，需要 wsl --shutdown

5.3 快速命令参考

# WSL2 命令
wsl --list -v          # 查看 WSL2 状态
wsl --shutdown         # 关闭 WSL2
wsl --install         # 安装 WSL2

# Claude Code 命令
npm install -g @anthropic-ai/claude-code  # 安装
claude --version                         # 验证版本

# 开发服务命令
php artisan serve --host=0.0.0.0 --port=8100
npm run dev -- --host=0.0.0.0

5.4 配置文件位置

~/.claude/settings.json   # API 配置
~/.claude/.claude.json    # 跳过登录向导

提示：本文以 MiniMax Coding Plan 为例进行配置，如果你使用其他 API 提供商（如硅基流动、智谱 AI），只需修改 settings.json 中的 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 即可。