WSL 踩坑指南
WSL 常用配置记录
网络模式
WSL 2 常见的网络模式主要有两种：NAT 和 mirrored。默认情况下，WSL 2 使用的是 NAT 模式。
Mirrored
mirrored 可以理解为镜像网络模式。开启后，WSL 会尽量镜像 Windows 的网络接口，让 WSL 和 Windows 处在更接近的网络语义中。
体验上更像：
- WSL 和 Windows 的网络行为更接近；
- WSL 可以更方便地使用 Windows 上的网络环境；
- VPN、公司代理、网络策略等复杂网络环境下，兼容性通常更好。
常见优势：
- 支持 IPv6；
- 在 WSL 内可以通过
127.0.0.1访问 Windows 上监听的服务； - 对 VPN 的兼容性更好；
- 支持组播；
- 局域网内其它设备可以更直接地访问 WSL 中运行的服务。
需要注意的是，mirrored 需要 Windows 11 22H2 或更高版本。如果系统版本较低，即使写了配置也可能不会生效。
NAT
NAT 是 WSL 2 默认的网络模式。
在这种模式下，Windows 主机相当于一个路由器，WSL 运行在一个独立的虚拟网段里。
典型特点：
- WSL 内部会有一个独立的私网 IP，例如
172.x.x.x或20.x.x.x； - WSL 主动访问外网一般没有问题；
- 外部设备访问 WSL 中的服务时，通常需要额外配置端口转发；
- Windows 主机可以通过
localhost:PORT访问 WSL 中监听的端口。
在 NAT 模式下，如果 WSL 中的程序监听了某个端口，并且 localhostForwarding 没有关闭，那么 Windows 通常可以通过同端口的 localhost 访问该服务。
例如，WSL 中启动了一个 Web 服务：
python3 -m http.server 3000
那么 Windows 侧一般可以访问：
http://localhost:3000
如果要让局域网中的其它设备访问 WSL 中的服务，则通常需要配置端口转发，或者改用 mirrored 网络模式。
文件系统
Windows 磁盘会挂载到 WSL 的 /mnt 目录下：
C:→/mnt/cD:→/mnt/d
WSL 发行版也会在 Windows 中暴露为 UNC 路径。例如 Ubuntu 的 Linux 文件系统根目录 / 通常可以通过下面的路径访问：
\\wsl$\Ubuntu\
新版 Windows 中也可能会看到类似路径：
\\wsl.localhost\Ubuntu\
一般建议：
- 如果在 Linux 命令行中工作，就把项目文件放在 WSL 的 Linux 文件系统中；
- 如果在 Windows 工具中工作，就把项目文件放在 Windows 文件系统中；
- 尽量避免频繁跨文件系统读写项目文件。
例如，在 WSL 中开发 Node.js、Go、Rust、Python 项目时，更推荐把项目放在：
/home/<用户名>/projects
而不是：
/mnt/c/Users/<用户名>/Desktop
这样通常可以减少权限、性能和文件监听方面的问题。
环境变量与互操作
WSL 启动时会注入一部分 Windows 环境变量，尤其是 Path。
默认情况下，WSL 会把 Windows 的 Path 转换成 /mnt 形式的路径，并追加到 Linux 的 $PATH 中。因此，在 WSL 中可以直接调用一些 Windows 程序。
例如：
notepad.exe
explorer.exe .
code .
WSL 也可以直接运行 Windows 的 .exe 程序。大多数情况下，WSL 会自动在 Linux 路径和 Windows 路径之间进行转换。
例如，在 WSL 中执行：
explorer.exe .
可以直接用 Windows 文件资源管理器打开当前目录。
不过，如果关闭了互操作或关闭了 Windows Path 注入，那么这些行为会受到影响。
配置文件
WSL 主要有两类配置文件：
- Windows 侧的全局配置文件：
C:\Users<用户名>.wslconfig - WSL 发行版内部的配置文件：
/etc/wsl.conf
它们的作用范围不同。
.wslconfig 影响所有 WSL 2 发行版，主要用于配置 WSL 2 虚拟机本身，例如网络模式、内存、CPU、代理、端口转发等。
/etc/wsl.conf 只影响当前发行版，主要用于配置当前 Linux 发行版的行为，例如默认用户、是否挂载 Windows 磁盘、是否启用 systemd、是否允许调用 Windows 程序等。
Windows 侧配置：.wslconfig
.wslconfig 位于 Windows 用户目录下：
C:\Users\<用户名>\.wslconfig
常见配置示例：
[wsl2]
networkingMode=mirrored
autoProxy=true
localhostForwarding=false
networkingMode
networkingMode 用于配置 WSL 2 的网络模式。
常见值包括：
networkingMode=nat
或：
networkingMode=mirrored
其中：
nat是默认模式；mirrored是镜像网络模式；bridged已经不推荐使用。
如果需要更好的 VPN、局域网访问、IPv6 或组播支持，可以尝试使用：
networkingMode=mirrored
autoProxy
autoProxy 用于控制是否自动把 Windows 的 HTTP 代理信息注入 WSL。
例如：
autoProxy=true
如果 Windows 已经配置了系统代理，开启后 WSL 会尝试自动使用 Windows 的代理信息。
不过，如果你使用的代理软件只监听 Windows 本机的 127.0.0.1，在 NAT 模式下可能会出现 WSL 无法直接使用该代理的问题。因为 WSL 里的 127.0.0.1 指向的是 WSL 自己，而不是 Windows 主机。
这种情况下可以考虑：
- 关闭
autoProxy，手动设置代理地址； - 将代理地址改成 WSL 能访问到的 Windows 主机地址；
- 在代理软件中开启允许局域网连接；
- 使用代理软件的 TUN 模式；
- 改用
mirrored网络模式。
localhostForwarding
localhostForwarding 用于控制 WSL 2 中监听的端口是否可以通过 Windows 主机的 localhost:PORT 访问。
例如：
localhostForwarding=true
默认情况下它是开启的。
在 NAT 模式下，如果 WSL 中启动了一个服务：
npm run dev
并监听在：
0.0.0.0:3000
或：
127.0.0.1:3000
那么 Windows 一般可以通过下面的地址访问：
http://localhost:3000
如果设置为：
localhostForwarding=false
那么 Windows 通过 localhost 访问 WSL 服务的行为可能会失效。
需要注意的是，在 mirrored 模式下，localhostForwarding 会被忽略。
WSL 侧配置：/etc/wsl.conf
/etc/wsl.conf 位于 WSL 发行版内部：
/etc/wsl.conf
常见配置示例：
[boot]
systemd=true
[user]
default=ruqiu
[interop]
enabled=false
appendWindowsPath=false
[automount]
enabled=true
root=/mnt
boot.systemd
boot.systemd 用于设置是否启用 systemd。
[boot]
systemd=true
开启后，WSL 启动时会使用 systemd 作为 PID 1。这样可以更接近普通 Linux 发行版的使用体验，也方便使用一些依赖 systemd 的服务。
例如：
systemctl status
如果启用了 systemd，就可以正常使用许多 systemctl 相关命令。
不过，开启 systemd 后，WSL 启动可能会比极简模式略慢一点。
user.default
user.default 用于设置默认登录用户。
[user]
default=ruqiu
设置后，从 Windows 直接打开该 WSL 发行版时，会默认进入 ruqiu 用户。
这大致等价于：
wsl -u ruqiu
如果不设置，WSL 通常会使用发行版首次初始化时创建的用户。
interop.enabled
interop.enabled 用于控制 WSL 和 Windows 之间的互操作能力。
[interop]
enabled=false
关闭后，WSL 中将不能直接调用 Windows 的 .exe 程序。
例如，下面这些命令可能会失效：
notepad.exe
explorer.exe .
code .
如果你不希望 WSL 调用 Windows 程序，可以关闭它。
interop.appendWindowsPath
interop.appendWindowsPath 用于控制是否把 Windows 的 Path 注入到 WSL 的 $PATH 中。
[interop]
appendWindowsPath=false
关闭后，Windows 的 PATH 不会再自动追加到 WSL 中。
需要注意的是，enabled 和 appendWindowsPath 是两个不同的配置。
即使：
enabled=true
但如果：
appendWindowsPath=false
那么 WSL 仍然支持调用 Windows 程序，只是不能再依赖 PATH 自动找到这些 .exe。这时需要手动指定完整路径。
automount.enabled
automount.enabled 用于控制是否自动挂载 Windows 磁盘。
[automount]
enabled=true
默认情况下，Windows 磁盘会自动挂载到 /mnt 下。
例如：
/mnt/c
/mnt/d
如果设置为：
[automount]
enabled=false
那么 Windows 磁盘不会自动挂载到 WSL 中。
不过，这只影响 Windows 磁盘是否挂载到 WSL 内部，不影响 Windows 通过 \wsl$ 或 \wsl.localhost 访问 WSL 文件系统。
automount.root
automount.root 用于设置 Windows 磁盘挂载到 WSL 中的位置。
默认位置是：
root=/mnt
此时挂载结果为：
C: -> /mnt/c
D: -> /mnt/d
如果修改为：
root=/
那么挂载结果可能会变成：
C: -> /c
D: -> /d
一般情况下保持默认的 /mnt 即可。
应用配置
修改 .wslconfig 或 /etc/wsl.conf 后，需要重启 WSL 才能应用配置。
可以在 PowerShell 中执行：
wsl --shutdown
然后重新打开 WSL。
也可以查看当前是否还有正在运行的发行版：
wsl --list --running
如果只想关闭某个发行版，可以使用：
wsl --terminate <发行版名称>
例如：
wsl --terminate Ubuntu
小结
简单来说：
.wslconfig是 Windows 侧的全局 WSL 2 配置；/etc/wsl.conf是单个 WSL 发行版内部的配置；NAT是 WSL 2 默认网络模式；mirrored更适合 VPN、局域网访问、IPv6、组播等场景；- Windows 磁盘默认挂载到
/mnt/c、/mnt/d等路径； - WSL 文件系统可以通过
\wsl$或\wsl.localhost从 Windows 访问； - 修改配置后，需要执行
wsl --shutdown或等待 WSL 完全退出后重新启动。