WSL 2 安装与通用配置指南

为什么选 WSL2

如果你在 Windows 上做开发，大概率遇到过这些问题：

node_modules 安装慢、next dev 热更新卡顿
Python 编译 C 扩展动不动就报错
Shell 脚本在 PowerShell / Git Bash 里跑得别扭
Docker Desktop 启动要半天

WSL2 是微软官方给出的解决方案——在 Windows 上跑一个真正的 Linux 内核，不用双系统重启切换，和 Windows 无缝共存。

适合用 WSL2 的场景：

Next.js、Node.js 后端开发（文件监听和 I/O 性能更好）
Python Agent 项目（工具链兼容性完整）
Claude Code / OpenCode 等终端 AI 工具（Linux shell 原生体验）
Docker 和 DevOps 工具链

不太需要的场景：

Obsidian 插件开发（需直接读写 Windows 文件系统）
.NET / C# 开发（Windows 本身就是一等公民）
游戏开发、移动端开发

Linux 发行版选择

版本	特点	推荐度
Ubuntu 24.04 LTS	2024 年发布，支持至 2029 年；软件包较新（Node.js 18+、Python 3.12+）；社区资源丰富	首选
Ubuntu 22.04 LTS	极致稳定，但软件包偏旧	保守场景
Debian 12	轻量纯净，但社区支持不如 Ubuntu	不推荐新手
Arch Linux (WSL)	滚动更新，始终最新，维护成本高	进阶用户

安装步骤

步骤 1：以管理员身份打开 PowerShell

右键开始菜单 → 选择「终端(管理员)」或「Windows PowerShell(管理员)」。

步骤 2：一行命令安装

powershell

wsl --install -d Ubuntu-24.04

这条命令会自动完成：

启用「适用于 Linux 的 Windows 子系统」功能
启用「虚拟机平台」功能
下载并安装 WSL2 Linux 内核
安装 Ubuntu 24.04

步骤 3：重启电脑

安装完成后按提示重启。

步骤 4：初始化 Ubuntu

重启后会自动弹出 Ubuntu 终端，按提示设置：

用户名：小写英文字母（如 bowie）
密码：输入时屏幕不显示字符，这是正常的

密码务必牢记，执行 sudo 命令时需要。

步骤 5：验证安装

bash

# 查看 WSL 版本，VERSION 列应显示 2
wsl -l -v

# 查看 Ubuntu 版本
lsb_release -a

关键配置（安装完立刻做）

限制 WSL2 内存占用

WSL2 默认占用 Windows 50% 物理内存且不主动释放。在 Windows 用户目录下创建配置文件：

文件路径： %USERPROFILE%\.wslconfig

ini

[wsl2]
memory=8GB
swap=4GB
processors=4

[experimental]
autoMemoryReclaim=gradual

参数	说明	建议值
`memory`	最大内存	物理内存的 25%–40%
`swap`	交换空间	2–4GB
`processors`	CPU 核心数	总核心数的 50%
`autoMemoryReclaim`	自动回收空闲内存	`gradual`

修改后在 PowerShell 中执行 wsl --shutdown 使配置生效。

启用 systemd

新版 WSL2 默认已开启 systemd，Docker 及各类后台服务都依赖它。确认一下：

bash

cat /etc/wsl.conf

如果没有，手动写入：

bash

sudo tee /etc/wsl.conf << 'EOF'
[boot]
systemd=true
EOF

然后 wsl --shutdown 重启 WSL，验证：

bash

systemctl list-units --type=service | head -5

配置 APT 镜像源（国内网络必备）

bash

sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak
sudo sed -i 's|https://archive.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list.d/ubuntu.sources
sudo sed -i 's|https://security.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list.d/ubuntu.sources
sudo apt update

安装基础开发工具

bash

sudo apt install -y build-essential git curl wget unzip \
  ripgrep fd-find fzf tree htop zip fonts-noto-cjk-mono

fonts-noto-cjk-mono：中文字体，避免终端中文显示为方块
ripgrep / fd-find：Claude Code 等工具依赖的高性能搜索工具
fzf / tree / htop：日常开发效率工具

开发环境搭建

Node.js（Next.js 项目）

推荐用 nvm 管理多版本：

bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
node -v && npm -v

Python（Agent 项目）

bash

sudo apt install -y python3 python3-pip python3-venv

# pip 国内镜像加速
mkdir -p ~/.pip
cat > ~/.pip/pip.conf << 'EOF'
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
EOF

VSCode Remote-WSL

Windows 侧正常安装 VSCode
Ubuntu 终端中执行 code .，VSCode 会自动提示安装 Remote - WSL 扩展
安装后左下角显示 WSL: Ubuntu-24.04，表示已连接

VSCode Server 运行在 WSL 内（消耗 WSL 内存），客户端运行在 Windows 侧（消耗 Windows 内存），合计可能占用 4–8GB。合理配置 .wslconfig 的内存限制很重要。

Git 配置

bash

git config --global user.name "Your Name"
git config --global user.email "your@email.com"
git config --global init.defaultBranch main
git config --global core.quotepath false  # 中文文件名不转义
git config --global credential.helper store

Claude Code / OpenCode

WSL2 终端环境直接安装，Linux 下 Shell 命令执行更原生：

bash

# Claude Code
npm install -g @anthropic-ai/claude-code

# OpenCode 按官方文档在 WSL 终端中安装

重要注意事项

项目文件必须放 Linux 分区

这是 WSL2 性能的关键。跨文件系统访问（Linux 访问 Windows 路径）I/O 性能暴跌。

bash

# 正确 -- Linux 文件系统，I/O 接近原生
cd ~/projects/nextjs-app

# 错误 -- 跨文件系统，性能严重下降
cd /mnt/c/Users/bowie/projects/nextjs-app

VSCode 通过 Remote-WSL 访问 ~/projects 时完全透明，体验和本地开发一致。Obsidian 插件开发是例外，需要在 Windows 原生环境操作。

VPN / 代理配置

WSL2 使用独立虚拟网卡，无法直接用 Windows 侧代理。在 ~/.bashrc 中配置：

bash

export hostip=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
export https_proxy="http://${hostip}:7890"
export http_proxy="http://${hostip}:7890"

端口号根据实际代理工具调整。不需要代理时注释掉即可。

不要在 WSL 中装 GUI 桌面

IDE、浏览器、Obsidian 都在 Windows 侧运行，WSL 只做终端和开发服务器。WSLg 支持 Linux GUI 应用但稳定性不够，不建议依赖。

各项目环境分配

项目	环境	原因
Next.js	WSL2	npm 安装快，热更新稳定
Obsidian 插件	Windows 原生	需直接读写 `.obsidian/plugins/`
OpenClaw / Hermes	WSL2	Python 工具链兼容性好
Claude Code	WSL2	Linux shell 原生体验
OpenCode	WSL2	终端工具 Linux 环境最佳

日常管理命令

powershell

# 完全关闭 WSL（释放内存）
wsl --shutdown

# 启动指定发行版
wsl -d Ubuntu-24.04

# 查看所有发行版及运行状态
wsl --list -v

# 导出备份
wsl --export Ubuntu-24.04 D:\backup\ubuntu.tar

# 从备份恢复
wsl --import Ubuntu-24.04 D:\backup ubuntu.tar

# 仅关闭指定发行版
wsl --terminate Ubuntu-24.04

常见问题排查

问题	解决方案
`wsl --install` 报错	Win10 需 1903+（内部版本 18362+），Win11 均支持；检查是否已开启虚拟机平台功能
内存持续增长不释放	确认 `.wslconfig` 中 `autoMemoryReclaim=gradual`；手动 `wsl --shutdown`
`next dev` 热更新不生效	确认项目在 `~/projects` 而非 `/mnt/c/` 下
终端中文显示方块	`sudo apt install fonts-noto-cjk-mono`
Git 提交中文文件名乱码	`git config --global core.quotepath false`
systemd 服务无法启动	检查 `/etc/wsl.conf` 中 `systemd=true`，执行 `wsl --shutdown` 后重启

为什么选 WSL2

如果你在 Windows 上做开发，大概率遇到过这些问题：

node_modules 安装慢、next dev 热更新卡顿
Python 编译 C 扩展动不动就报错
Shell 脚本在 PowerShell / Git Bash 里跑得别扭
Docker Desktop 启动要半天

WSL2 是微软官方给出的解决方案——在 Windows 上跑一个真正的 Linux 内核，不用双系统重启切换，和 Windows 无缝共存。

适合用 WSL2 的场景：

Next.js、Node.js 后端开发（文件监听和 I/O 性能更好）
Python Agent 项目（工具链兼容性完整）
Claude Code / OpenCode 等终端 AI 工具（Linux shell 原生体验）
Docker 和 DevOps 工具链

不太需要的场景：

Obsidian 插件开发（需直接读写 Windows 文件系统）
.NET / C# 开发（Windows 本身就是一等公民）
游戏开发、移动端开发

Linux 发行版选择

版本	特点	推荐度
Ubuntu 24.04 LTS	2024 年发布，支持至 2029 年；软件包较新（Node.js 18+、Python 3.12+）；社区资源丰富	首选
Ubuntu 22.04 LTS	极致稳定，但软件包偏旧	保守场景
Debian 12	轻量纯净，但社区支持不如 Ubuntu	不推荐新手
Arch Linux (WSL)	滚动更新，始终最新，维护成本高	进阶用户

安装步骤

步骤 1：以管理员身份打开 PowerShell

右键开始菜单 → 选择「终端(管理员)」或「Windows PowerShell(管理员)」。

步骤 2：一行命令安装

powershell

wsl --install -d Ubuntu-24.04

这条命令会自动完成：

启用「适用于 Linux 的 Windows 子系统」功能
启用「虚拟机平台」功能
下载并安装 WSL2 Linux 内核
安装 Ubuntu 24.04

步骤 3：重启电脑

安装完成后按提示重启。

步骤 4：初始化 Ubuntu

重启后会自动弹出 Ubuntu 终端，按提示设置：

用户名：小写英文字母（如 bowie）
密码：输入时屏幕不显示字符，这是正常的

密码务必牢记，执行 sudo 命令时需要。

步骤 5：验证安装

bash

# 查看 WSL 版本，VERSION 列应显示 2
wsl -l -v

# 查看 Ubuntu 版本
lsb_release -a

关键配置（安装完立刻做）

限制 WSL2 内存占用

WSL2 默认占用 Windows 50% 物理内存且不主动释放。在 Windows 用户目录下创建配置文件：

文件路径： %USERPROFILE%\.wslconfig

ini

[wsl2]
memory=8GB
swap=4GB
processors=4

[experimental]
autoMemoryReclaim=gradual

参数	说明	建议值
`memory`	最大内存	物理内存的 25%–40%
`swap`	交换空间	2–4GB
`processors`	CPU 核心数	总核心数的 50%
`autoMemoryReclaim`	自动回收空闲内存	`gradual`

修改后在 PowerShell 中执行 wsl --shutdown 使配置生效。

启用 systemd

新版 WSL2 默认已开启 systemd，Docker 及各类后台服务都依赖它。确认一下：

bash

cat /etc/wsl.conf

如果没有，手动写入：

bash

sudo tee /etc/wsl.conf << 'EOF'
[boot]
systemd=true
EOF

然后 wsl --shutdown 重启 WSL，验证：

bash

systemctl list-units --type=service | head -5

配置 APT 镜像源（国内网络必备）

bash

sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak
sudo sed -i 's|https://archive.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list.d/ubuntu.sources
sudo sed -i 's|https://security.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list.d/ubuntu.sources
sudo apt update

安装基础开发工具

bash

sudo apt install -y build-essential git curl wget unzip \
  ripgrep fd-find fzf tree htop zip fonts-noto-cjk-mono

fonts-noto-cjk-mono：中文字体，避免终端中文显示为方块
ripgrep / fd-find：Claude Code 等工具依赖的高性能搜索工具
fzf / tree / htop：日常开发效率工具

开发环境搭建

Node.js（Next.js 项目）

推荐用 nvm 管理多版本：

bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
node -v && npm -v

Python（Agent 项目）

bash

sudo apt install -y python3 python3-pip python3-venv

# pip 国内镜像加速
mkdir -p ~/.pip
cat > ~/.pip/pip.conf << 'EOF'
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
EOF

VSCode Remote-WSL

Windows 侧正常安装 VSCode
Ubuntu 终端中执行 code .，VSCode 会自动提示安装 Remote - WSL 扩展
安装后左下角显示 WSL: Ubuntu-24.04，表示已连接

VSCode Server 运行在 WSL 内（消耗 WSL 内存），客户端运行在 Windows 侧（消耗 Windows 内存），合计可能占用 4–8GB。合理配置 .wslconfig 的内存限制很重要。

Git 配置

bash

git config --global user.name "Your Name"
git config --global user.email "your@email.com"
git config --global init.defaultBranch main
git config --global core.quotepath false  # 中文文件名不转义
git config --global credential.helper store

Claude Code / OpenCode

WSL2 终端环境直接安装，Linux 下 Shell 命令执行更原生：

bash

# Claude Code
npm install -g @anthropic-ai/claude-code

# OpenCode 按官方文档在 WSL 终端中安装

重要注意事项

项目文件必须放 Linux 分区

这是 WSL2 性能的关键。跨文件系统访问（Linux 访问 Windows 路径）I/O 性能暴跌。

bash

# 正确 -- Linux 文件系统，I/O 接近原生
cd ~/projects/nextjs-app

# 错误 -- 跨文件系统，性能严重下降
cd /mnt/c/Users/bowie/projects/nextjs-app

VSCode 通过 Remote-WSL 访问 ~/projects 时完全透明，体验和本地开发一致。Obsidian 插件开发是例外，需要在 Windows 原生环境操作。

VPN / 代理配置

WSL2 使用独立虚拟网卡，无法直接用 Windows 侧代理。在 ~/.bashrc 中配置：

bash

export hostip=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
export https_proxy="http://${hostip}:7890"
export http_proxy="http://${hostip}:7890"

端口号根据实际代理工具调整。不需要代理时注释掉即可。

不要在 WSL 中装 GUI 桌面

IDE、浏览器、Obsidian 都在 Windows 侧运行，WSL 只做终端和开发服务器。WSLg 支持 Linux GUI 应用但稳定性不够，不建议依赖。

各项目环境分配

项目	环境	原因
Next.js	WSL2	npm 安装快，热更新稳定
Obsidian 插件	Windows 原生	需直接读写 `.obsidian/plugins/`
OpenClaw / Hermes	WSL2	Python 工具链兼容性好
Claude Code	WSL2	Linux shell 原生体验
OpenCode	WSL2	终端工具 Linux 环境最佳

日常管理命令

powershell

# 完全关闭 WSL（释放内存）
wsl --shutdown

# 启动指定发行版
wsl -d Ubuntu-24.04

# 查看所有发行版及运行状态
wsl --list -v

# 导出备份
wsl --export Ubuntu-24.04 D:\backup\ubuntu.tar

# 从备份恢复
wsl --import Ubuntu-24.04 D:\backup ubuntu.tar

# 仅关闭指定发行版
wsl --terminate Ubuntu-24.04

常见问题排查

问题	解决方案
`wsl --install` 报错	Win10 需 1903+（内部版本 18362+），Win11 均支持；检查是否已开启虚拟机平台功能
内存持续增长不释放	确认 `.wslconfig` 中 `autoMemoryReclaim=gradual`；手动 `wsl --shutdown`
`next dev` 热更新不生效	确认项目在 `~/projects` 而非 `/mnt/c/` 下
终端中文显示方块	`sudo apt install fonts-noto-cjk-mono`
Git 提交中文文件名乱码	`git config --global core.quotepath false`
systemd 服务无法启动	检查 `/etc/wsl.conf` 中 `systemd=true`，执行 `wsl --shutdown` 后重启