WSL 2 架构与版本选型指南

WSL 2 是什么

WSL 2（Windows Subsystem for Linux 2）是微软为 Windows 提供的 Linux 子系统的新一代架构。它允许你在 Windows 上直接运行完整的 Linux 环境，包括命令行工具、实用工具和应用程序，无需双系统重启或传统虚拟机的开销。

WSL 2 支持安装和运行多种 Linux 发行版（Ubuntu、Debian、Kali、Arch Linux 等），将文件存储在独立的 Linux 文件系统中，可以运行 Bash 脚本、GNU/Linux 命令行应用、各类语言工具链（Node.js、Python、Rust、Go、C/C++ 等）以及常见服务（MySQL、PostgreSQL、MongoDB、Apache、SSHD）。此外，WSL 2 支持运行 Linux GUI 应用（WSLg）、GPU 加速机器学习训练，并且已经完全开源。

WSL 2 还是一个开源项目，源代码可在 Microsoft/WSL 获取。

WSL 2 架构原理

核心变化：从转换层到真实 Linux 内核

WSL 1 和 WSL 2 之间最大的区别在于底层架构：

WSL 1 使用的是由微软 WSL 团队自行编写的转换层。它拦截 Linux 系统调用并将其翻译为 Windows NT API 调用，本质上不包含真正的 Linux 内核。这种方式实现轻量，但系统调用兼容性不完整——不是所有 Linux 应用都能正常运行。

WSL 2 则使用了最新的虚拟化技术，在轻量级实用工具虚拟机（Utility VM）内运行一个真正的 Linux 内核。这个内核由微软基于 kernel.org 的最新稳定分支构建，并专门针对 WSL 2 进行了优化（特别是在文件大小和性能方面）。内核通过 Windows Update 自动推送安全补丁和改进，无需用户自行管理。

WSL 2 的 Linux 发行版作为托管 VM 内的独立容器运行，多个发行版共享同一网络命名空间、设备树、CPU/内核/内存/交换空间以及 /init 二进制文件，但各自拥有独立的 PID 命名空间、装载命名空间、用户命名空间、Cgroup 命名空间和 init 进程。

WSL 2 的三大优势

完整 Linux 内核

因为运行的是真正的 Linux 内核，WSL 2 获得了与裸机 Linux 几乎一致的系统调用兼容性。这意味着以前在 WSL 1 上无法运行的应用（如 Docker）现在可以正常使用，且 Linux 内核的任何更新都可以立即获得，无需等待 WSL 团队实现。

文件 IO 性能大幅提升

WSL 2 在文件密集型操作上的表现远超 WSL 1：

解压压缩 tarball：最快可达 20 倍速度提升
git clone、npm install、cmake：约 2-5 倍速度提升

以上性能提升适用于 Linux 文件系统内部的文件操作。跨文件系统（Linux 访问 Windows 路径）的性能，WSL 2 反而不如 WSL 1。这也是为什么项目文件必须放在 Linux 文件系统内（如）的根本原因。

轻量级虚拟机，但体验接近原生

传统的虚拟机体验通常启动慢、资源占用高、需要手动管理。WSL 2 虽然使用了 VM 技术，但它在后台自动管理和运行，用户获得的体验与 WSL 1 一致：快速启动、低资源占用、Windows 和 Linux 之间无缝集成。

WSL 1 vs WSL 2 功能对比

功能	WSL 1	WSL 2
Windows 与 Linux 集成	✅	✅
快速启动	✅	✅
低资源占用（对比传统 VM）	✅	✅
兼容 VMware / VirtualBox	✅	❌
托管虚拟机	❌	✅
完整 Linux 内核	❌	✅
完整系统调用兼容性	❌	✅
跨 OS 文件系统性能	✅	❌
systemd 支持	❌	✅
IPv6 支持	✅	✅
GPU 加速	❌	✅
Linux GUI 应用（WSLg）	❌	✅
USB 设备连接	❌	✅（通过 usbipd-win）

关键结论：WSL 2 在绝大多数维度上优于 WSL 1，唯一的例外是跨操作系统文件系统的访问性能。

何时选择 WSL 1

虽然 WSL 2 是默认且推荐的版本，但以下场景可能更适合 WSL 1：

1. 项目文件必须存储在 Windows 文件系统上

如果你的项目因为某些原因只能存放在 Windows 分区（如 /mnt/c/），且无法迁移到 Linux 文件系统，WSL 1 访问 Windows 文件的速度更快。

2. 需要在同一文件上交叉使用 Windows 和 Linux 工具

WSL 1 在跨操作系统文件操作上的性能优于 WSL 2。如果你频繁在 Windows 和 Linux 工具之间切换处理同一文件（比如用 Windows IDE 编辑、Linux 工具编译），WSL 1 的跨系统 I/O 体验更好。

3. 依赖 VMware 或 VirtualBox

WSL 2 的 Hyper-V 虚拟化层与 VMware/VirtualBox 存在冲突。WSL 2 可以与 VMware 15.5.5+ 共存，但 VirtualBox 6+ 虽然声称支持 WSL，实际上仍有重大兼容性问题。

4. 内存资源极其有限

WSL 2 的内存使用会随使用增长，虽然进程释放的内存会自动归还 Windows，但缓存页在 WSL 实例关闭前不会释放。长时间运行或访问大量文件时，缓存可能占用较多 Windows 内存。可以通过 .wslconfig 中的 autoMemoryReclaim=gradual 缓解这个问题。

如果上述场景都不适用于你，请直接使用 WSL 2。实际开发中，绝大多数情况都应该选择 WSL 2。

系统要求

要求	最低版本
Windows 10	内部版本 1903（18362）或更高
Windows 11	所有版本均支持
CPU	支持虚拟化（通常 BIOS 中默认开启）
内存	建议 8GB 以上
磁盘	约 1GB（WSL 组件）+ 发行版大小

检查 Windows 版本：Win + R → 输入 winver → 查看「OS 内部版本」，你会看到类似这样的窗口。

winver

安装 WSL 2

一键安装（推荐）

如果你使用 Windows 10 1903+ 或 Windows 11，一条命令即可完成所有操作：

powershell

wsl --install

这会自动启用 WSL 功能、安装虚拟机平台、下载 Linux 内核、安装默认的 Ubuntu 发行版。

安装完成后需要重启电脑。

当然，你也可以指定任意发行版安装。以 Ubuntu-24.04 为例，先通过以下命令查看所有可用发行版：

powershell

wsl --list --online

也可以用简写命令：

powershell

wsl -l -o

然后执行以下命令进行安装：

powershell

wsl --install -d Ubuntu-24.04

其他发行版只需把 Ubuntu-24.04 替换为对应的版本号。

“Create a default Unix user account:”填一个用户名。

“New password:”设置一个密码。

“Retype new password:”再输一次密码确认。

输入密码时，密码是不可见的。这是 Linux 的特性，不用担心，输完直接回车即可。

接下来会提示你“passwd: password updated successfully”。

有两个命令：

To run a command as administrator (user "root"), use "sudo <command>". See "man sudo_root" for details.

手动安装

如果你的系统是 Windows 10 1903+（内部版本 18362+）或 Windows 11，就是首选方式。下面的手动安装步骤适合需要了解每一步做了什么，或者自动安装失败需要手动排查的场景。

步骤 1：以管理员身份打开 PowerShell（右键开始菜单 → 选择「终端(管理员)」）

步骤 2：启用「适用于 Linux 的 Windows 子系统」

powershell

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

步骤 3：启用「虚拟机平台」

powershell

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

步骤 4：重启电脑（上述功能启用需要重启生效）

步骤 5：下载并安装 WSL2 Linux 内核更新包

powershell

curl -o $env:TEMP\wsl_update_x64.msi https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi
msiexec /i $env:TEMP\wsl_update_x64.msi /quiet /norestart

步骤 6：将 WSL 2 设为默认版本

powershell

wsl --set-default-version 2

步骤 7：安装 Ubuntu 24.04

powershell

wsl --install -d Ubuntu-24.04

初始化 Ubuntu

重启后会自动弹出 Ubuntu 终端窗口，按提示完成初始化：

用户名：小写英文字母（如 bowie），建议用常用 GitHub 用户名
密码：输入时屏幕不显示任何字符，这是 Linux 的正常行为，连续输入两次确认即可

密码务必牢记，执行 sudo 提权命令时会频繁用到。Linux 中密码输入不回显是安全设计，不是卡住了。

如果没有自动弹出终端，在开始菜单搜索「Ubuntu 24.04」手动打开。

验证安装

bash

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

# 查看 Ubuntu 版本
lsb_release -a

如果 VERSION 显示为 1，手动升级：

powershell

wsl --set-version Ubuntu-24.04 2

WSL 1 和 WSL 2 之间的转换对于包含大型项目的发行版可能非常耗时，甚至因架构差异导致失败。转换前建议先备份文件。

Microsoft Store 版本的 WSL

WSL 已从 Windows OS 映像中独立出来，作为 Microsoft Store 包分发。这意味着你可以无需等待 Windows 系统更新即可获得最新的 WSL 功能和服务。

从 Windows 10 版本 19044+ 开始，wsl --install 会自动从 Microsoft Store 安装 WSL。如果你已经在使用 WSL，可以手动更新：

powershell

wsl --update

如果组织环境无法访问 Microsoft Store，可以使用网络下载方式：

powershell

wsl --update --web-download

从 WSL 1 升级到 WSL 2

如果已有发行版运行在 WSL 1 上，可以逐个升级：

powershell

# 查看当前版本
wsl -l -v

# 升级指定发行版
wsl --set-version <发行版名称> 2

# 设置默认版本（新安装的发行版将使用此版本）
wsl --set-default-version 2

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

以下配置的完整参数说明参见《WSL 2 配置、命令与运维手册》。

限制内存占用

WSL 2 默认占用 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

新版 WSL 2 默认已开启 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：日常开发效率工具

开发环境搭建

VS Code + Remote-WSL

VS Code 与 WSL 的组合是最推荐的 Windows 上 Linux 开发方案。VS Code 通过「客户端-服务器」架构实现远程开发：客户端（UI）运行在 Windows 侧，服务器（代码、Git、扩展）运行在 WSL 内。

在 Windows 上正常安装 VS Code
安装时勾选「添加到 PATH」
在 WSL 终端中执行 code .，VS Code 会自动提示安装 Remote - WSL 扩展
安装后左下角显示 WSL: Ubuntu-24.04 表示已连接

安装后你可以获得：IntelliSense 代码补全、Linting、调试、代码片段、单元测试、Git 集成等全部功能，同时项目文件存储在 Linux 文件系统中，避免跨文件系统性能损失。

部分扩展（如 Python 扩展）需要单独安装在 WSL 环境中。如果 VS Code 显示警告图标和绿色的「在 WSL 中安装」按钮，点击即可。

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

Windows Terminal

Windows Terminal 支持多标签页（在 PowerShell、CMD 和多个 Linux 发行版之间快速切换）、自定义键绑定、自定义主题（配色方案、字体、背景透明度等）。

在 Microsoft Store 搜索「Windows Terminal」安装，安装后打开 Terminal → 设置 → 自定义 profile。

Node.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 环境

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

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

core.quotepath false 确保中文文件名在 git status 中正常显示而不被转义。

Claude Code / OpenCode

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

bash

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

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

文件系统最佳实践

核心原则：项目文件放在 Linux 文件系统内。

bash

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

# ❌ 错误 -- 跨文件系统访问，性能严重下降
cd /mnt/c/Users/you/projects/my-app

从 Windows 访问 Linux 文件：

文件资源管理器地址栏输入 \\wsl$\Ubuntu-24.04\
或在 WSL 终端中执行 explorer.exe .

不要使用 Windows 工具修改 WSL 文件夹中的文件（如 %APPDATA%\... 下的 WSL 相关文件），可能导致发行版损坏。

各项目环境分配

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

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

常见问题排查

问题	解决方案
`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` 后重启
WSL 1 → WSL 2 升级失败	转换前先 `wsl --export` 备份发行版；确认 Windows 版本 >= 1903

WSL 2 是什么

WSL 2 还是一个开源项目，源代码可在 Microsoft/WSL 获取。

WSL 2 架构原理

核心变化：从转换层到真实 Linux 内核

WSL 1 和 WSL 2 之间最大的区别在于底层架构：

WSL 2 的三大优势

完整 Linux 内核

文件 IO 性能大幅提升

WSL 2 在文件密集型操作上的表现远超 WSL 1：

解压压缩 tarball：最快可达 20 倍速度提升
git clone、npm install、cmake：约 2-5 倍速度提升

轻量级虚拟机，但体验接近原生

WSL 1 vs WSL 2 功能对比

功能	WSL 1	WSL 2
Windows 与 Linux 集成	✅	✅
快速启动	✅	✅
低资源占用（对比传统 VM）	✅	✅
兼容 VMware / VirtualBox	✅	❌
托管虚拟机	❌	✅
完整 Linux 内核	❌	✅
完整系统调用兼容性	❌	✅
跨 OS 文件系统性能	✅	❌
systemd 支持	❌	✅
IPv6 支持	✅	✅
GPU 加速	❌	✅
Linux GUI 应用（WSLg）	❌	✅
USB 设备连接	❌	✅（通过 usbipd-win）

关键结论：WSL 2 在绝大多数维度上优于 WSL 1，唯一的例外是跨操作系统文件系统的访问性能。

何时选择 WSL 1

虽然 WSL 2 是默认且推荐的版本，但以下场景可能更适合 WSL 1：

1. 项目文件必须存储在 Windows 文件系统上

如果你的项目因为某些原因只能存放在 Windows 分区（如 /mnt/c/），且无法迁移到 Linux 文件系统，WSL 1 访问 Windows 文件的速度更快。

2. 需要在同一文件上交叉使用 Windows 和 Linux 工具

3. 依赖 VMware 或 VirtualBox

WSL 2 的 Hyper-V 虚拟化层与 VMware/VirtualBox 存在冲突。WSL 2 可以与 VMware 15.5.5+ 共存，但 VirtualBox 6+ 虽然声称支持 WSL，实际上仍有重大兼容性问题。

4. 内存资源极其有限

如果上述场景都不适用于你，请直接使用 WSL 2。实际开发中，绝大多数情况都应该选择 WSL 2。

系统要求

要求	最低版本
Windows 10	内部版本 1903（18362）或更高
Windows 11	所有版本均支持
CPU	支持虚拟化（通常 BIOS 中默认开启）
内存	建议 8GB 以上
磁盘	约 1GB（WSL 组件）+ 发行版大小

检查 Windows 版本：Win + R → 输入 winver → 查看「OS 内部版本」，你会看到类似这样的窗口。

winver

安装 WSL 2

一键安装（推荐）

如果你使用 Windows 10 1903+ 或 Windows 11，一条命令即可完成所有操作：

powershell

wsl --install

这会自动启用 WSL 功能、安装虚拟机平台、下载 Linux 内核、安装默认的 Ubuntu 发行版。

安装完成后需要重启电脑。

当然，你也可以指定任意发行版安装。以 Ubuntu-24.04 为例，先通过以下命令查看所有可用发行版：

powershell

wsl --list --online

也可以用简写命令：

powershell

wsl -l -o

然后执行以下命令进行安装：

powershell

wsl --install -d Ubuntu-24.04

其他发行版只需把 Ubuntu-24.04 替换为对应的版本号。

“Create a default Unix user account:”填一个用户名。

“New password:”设置一个密码。

“Retype new password:”再输一次密码确认。

输入密码时，密码是不可见的。这是 Linux 的特性，不用担心，输完直接回车即可。

接下来会提示你“passwd: password updated successfully”。

有两个命令：

To run a command as administrator (user "root"), use "sudo <command>". See "man sudo_root" for details.

手动安装

步骤 1：以管理员身份打开 PowerShell（右键开始菜单 → 选择「终端(管理员)」）

步骤 2：启用「适用于 Linux 的 Windows 子系统」

powershell

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

步骤 3：启用「虚拟机平台」

powershell

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

步骤 4：重启电脑（上述功能启用需要重启生效）

步骤 5：下载并安装 WSL2 Linux 内核更新包

powershell

curl -o $env:TEMP\wsl_update_x64.msi https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi
msiexec /i $env:TEMP\wsl_update_x64.msi /quiet /norestart

步骤 6：将 WSL 2 设为默认版本

powershell

wsl --set-default-version 2

步骤 7：安装 Ubuntu 24.04

powershell

wsl --install -d Ubuntu-24.04

初始化 Ubuntu

重启后会自动弹出 Ubuntu 终端窗口，按提示完成初始化：

用户名：小写英文字母（如 bowie），建议用常用 GitHub 用户名
密码：输入时屏幕不显示任何字符，这是 Linux 的正常行为，连续输入两次确认即可

密码务必牢记，执行 sudo 提权命令时会频繁用到。Linux 中密码输入不回显是安全设计，不是卡住了。

如果没有自动弹出终端，在开始菜单搜索「Ubuntu 24.04」手动打开。

验证安装

bash

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

# 查看 Ubuntu 版本
lsb_release -a

如果 VERSION 显示为 1，手动升级：

powershell

wsl --set-version Ubuntu-24.04 2

WSL 1 和 WSL 2 之间的转换对于包含大型项目的发行版可能非常耗时，甚至因架构差异导致失败。转换前建议先备份文件。

Microsoft Store 版本的 WSL

WSL 已从 Windows OS 映像中独立出来，作为 Microsoft Store 包分发。这意味着你可以无需等待 Windows 系统更新即可获得最新的 WSL 功能和服务。

从 Windows 10 版本 19044+ 开始，wsl --install 会自动从 Microsoft Store 安装 WSL。如果你已经在使用 WSL，可以手动更新：

powershell

wsl --update

如果组织环境无法访问 Microsoft Store，可以使用网络下载方式：

powershell

wsl --update --web-download

从 WSL 1 升级到 WSL 2

如果已有发行版运行在 WSL 1 上，可以逐个升级：

powershell

# 查看当前版本
wsl -l -v

# 升级指定发行版
wsl --set-version <发行版名称> 2

# 设置默认版本（新安装的发行版将使用此版本）
wsl --set-default-version 2

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

以下配置的完整参数说明参见《WSL 2 配置、命令与运维手册》。

限制内存占用

WSL 2 默认占用 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

新版 WSL 2 默认已开启 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：日常开发效率工具

开发环境搭建

VS Code + Remote-WSL

在 Windows 上正常安装 VS Code
安装时勾选「添加到 PATH」
在 WSL 终端中执行 code .，VS Code 会自动提示安装 Remote - WSL 扩展
安装后左下角显示 WSL: Ubuntu-24.04 表示已连接

部分扩展（如 Python 扩展）需要单独安装在 WSL 环境中。如果 VS Code 显示警告图标和绿色的「在 WSL 中安装」按钮，点击即可。

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

Windows Terminal

Windows Terminal 支持多标签页（在 PowerShell、CMD 和多个 Linux 发行版之间快速切换）、自定义键绑定、自定义主题（配色方案、字体、背景透明度等）。

在 Microsoft Store 搜索「Windows Terminal」安装，安装后打开 Terminal → 设置 → 自定义 profile。

Node.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 环境

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

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

core.quotepath false 确保中文文件名在 git status 中正常显示而不被转义。

Claude Code / OpenCode

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

bash

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

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

文件系统最佳实践

核心原则：项目文件放在 Linux 文件系统内。

bash

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

# ❌ 错误 -- 跨文件系统访问，性能严重下降
cd /mnt/c/Users/you/projects/my-app

从 Windows 访问 Linux 文件：

文件资源管理器地址栏输入 \\wsl$\Ubuntu-24.04\
或在 WSL 终端中执行 explorer.exe .

不要使用 Windows 工具修改 WSL 文件夹中的文件（如 %APPDATA%\... 下的 WSL 相关文件），可能导致发行版损坏。

各项目环境分配

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

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

常见问题排查

问题	解决方案
`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` 后重启
WSL 1 → WSL 2 升级失败	转换前先 `wsl --export` 备份发行版；确认 Windows 版本 >= 1903