WSL2 运行调式项目的详细配置

前言

很多 GitHub 项目默认就是按 Linux 环境 写的，里面会用到 Windows 没有或不兼容的东西，比如：

1
2
3
4
5
sudo apt install xxx
bash install.sh
chmod +x run.sh
./run.sh
make

这些命令在 Windows 的 CMD / PowerShell 里可能会报错，但在 WSL 的 Ubuntu里就能正常执行。

同时ubuntu系统配置环境比较简单方便。

如果你在 Windows 直接跑，可能会因为 bash、路径、权限、依赖不兼容报错；进入 WSL 后，相当于用 Linux 环境跑这个项目，更符合作者原本的运行环境。

最终选择是：保留 Windows 作为日常系统，把 WSL2 的 Ubuntu 环境迁移到 D 盘，并在 WSL 内部运行 Python、Git、HuggingFace等实验流程。这样 Windows 像办公桌，WSL 像实验台，数据和依赖尽量放在实验台里，减少 Windows 环境污染。

一、什么是WSL

WSL 全称是 Windows Subsystem for Linux，中文可以理解为：

1
Windows 里的 Linux 子系统

它的作用是：让你在 Windows 电脑里直接运行 Linux 环境，比如 Ubuntu、Debian，而不需要单独装双系统，也不需要开一个完整虚拟机。

你可以把 Windows 看成你的主电脑系统：

1
Windows = 主房子

WSL 就像 Windows 里面专门开出来的一个 Linux 工作间：

1
WSL = Windows 房子里的 Linux 工作间

你平时还是在 Windows 里使用电脑：

1
浏览器、微信、QQ、VS Code、文件资源管理器

但是当你要跑 GitHub上的 Linux 项目时，就可以进入 WSL：

1
wsl

然后你就进入了 Linux 环境，可以使用这些命令：

1
2
3
4
5
6
7
ls
cd
sudo apt install
python
pip
make
bash

简言之：

  1. Windows 是宿主系统
  2. WSL 是运行在 Windows 里面的 Linux 环境

WSL 本身只是一个机制，真正使用时你一般会安装一个 Linux 发行版，比如：

1
2
3
4
Ubuntu
Debian
Kali Linux
openSUSE

最常见的是 Ubuntu。

所以你平时说“进入 WSL”，很多时候其实是进入：

1
WSL 里的 Ubuntu

例如你打开终端后看到：

1
user@DESKTOP:~$

这就说明你已经在 Linux 环境里了。

二、WSL和windows宿主机的简单文件关系

WSL 和Windows可以互相访问文件。

2.1 WSL 访问 Windows 文件

Windows 的磁盘在 WSL 里通常是：

1
2
/mnt/c
/mnt/d

比如 Windows 里的：

1
D:\code\project

在 WSL 里可以这样访问：

1
cd /mnt/d/code/project

这说明 WSL可以看到 Windows 的 D 盘文件。

2.2 Windows 访问 WSL 文件

Windows 也可以访问 WSL 里面的文件。

在 Windows 文件资源管理器地址栏输入：

1
\\wsl$

就可以看到 WSL 里面的 Linux 文件。

比如：

1
\\wsl$\Ubuntu\home\你的用户名

这就是 WSL 的 Linux 用户目录。

2.3 WSL 里面的文件和 Windows 里的文件一样吗？

不完全一样。

首先这里是两个不一样的系统，两者之间的文件可以便捷的相互访问，但是不是说两个系统看到的是两个文件，wsl中可以看到windows环境中的文件，是因为windows磁盘挂载在wsl的 \mnt\目录下面。

什么是挂载：

挂载以后访问的确是同一个文件，不是复制了一份。

但问题在于：文件内容是同一个，文件所在的“文件系统规则”不是 Linux 原生规则。

可以先记住一句话：

挂载 = 给另一个文件系统开一个入口，不是复制，不是迁移，不是变成 Linux 文件

2.4 WSL、虚拟机、双系统有什么区别？

可以简单对比：

方式 理解 特点
WSL Windows 里的 Linux 子系统 轻量、方便、适合开发
虚拟机 Windows 里开一台虚拟 Linux 电脑 更完整，但更重
双系统 一台电脑装 Windows 和 Linux 两套系统 最独立，但切换麻烦

WSL 的优势是：

  1. 不用重启电脑
  2. 不用切换系统
  3. 可以在 Windows 上直接用 Linux 命令
  4. 可以配合 VS Code 开发

所以它特别适合这种情况：

  1. 平时用 Windows
  2. 但是 GitHub 项目需要 Linux 环境

三、最舒适的wsl使用方法

  1. win + r 进入powershell界面，输入 wsl
  2. 进入/home目录
  3. git clone代码仓库
  4. 运行code .，下载在wsl的项目就用vscode打开了。

比较方便的是打开之后还可以直接用codex。

image-20260603214730078

image-20260603214802150

注意：进入wsl之后，相关的项目环境都需要配置，windows配置好的环境不能直接在wsl中使用。

当这样打开项目之后，看到UTF-8 LF Shell Script 就相当于成功了，不用担心在vscode编辑代码时的换行符等等字符问题了。

image-20260603220244597

三、为什么要迁移 WSL 到 D 盘

WSL2 会把这个 Linux 文件系统存进一个虚拟磁盘文件 ext4.vhdx 里。

微软文档说明，WSL2 的每个 Linux 发行版都会用一个 VHD 虚拟硬盘保存 Linux 文件系统，这个文件在 Windows 磁盘上表现为 ext4.vhdx。

ext4.vhdx 可以理解成：WSL2 的 Linux 系统硬盘文件

它在 Windows 看起来只是一个文件：ext4.vhdx

image-20260603220640464

但对 WSL 里的 Ubuntu 来说，它就是自己的 Linux 磁盘，里面放着wsl自己的文件，比如前面克隆的项目，或者运行项目配置的环境，都在这里。

但是windows中挂载进来的文件不在这里。

通常默认情况下，这个 ext4.vhdx 可能在 C 盘。

你在 WSL 里：

1
2
3
4
5
git clone 项目
pip install 依赖
conda create 环境
npm install
...

都会写进 ext4.vhdx。

如果 ext4.vhdx 在 C 盘，那么 C 盘会越来越大。

迁移 WSL 到 D 盘，在 WSL 里下载项目、安装依赖，占用的主要就是 D 盘空间，而不是 C 盘。

微软文档也提到，WSL 的 VHD 会随着使用增长，占用 Windows 磁盘空间。

四、如何迁移

迁移 WSL 的核心思路是四步：关机、导出、重新导入、设置默认。

可以把它理解成先把旧系统打包成一个 tar 快照，再把这个快照恢复到 D 盘的新位置。

先查真实名称：列出你电脑里安装的所有 WSL 发行版，并显示它们的状态和版本

1
wsl -l -v

可以看到

1
2
3
NAME              STATE      VERSION
docker-desktop    Running    2
Ubuntu            Running    2

其中docker-desktop是 Docker Desktop 自己创建的 WSL 环境，主要给Docker用的，一般不要手动动它。

迁移 WSL 的核心思路是四步：关机、导出、重新导入、设置默认。

参考命令如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# 1. 关闭所有正在运行的 WSL 发行版
# 这样可以避免导出时文件还在被占用
wsl --shutdown


# 2. 在 D 盘创建一个备份目录
# 用来存放从原 Ubuntu 导出的 tar 备份文件
mkdir D:\wsl-backup


# 3. 在 D 盘创建一个新的 WSL 存放目录
# 以后新的 Ubuntu-D 的虚拟硬盘 ext4.vhdx 会放在这里
mkdir D:\wsl


# 4. 把当前名为 Ubuntu 的 WSL 系统导出成一个 tar 文件
# Ubuntu 是原来的 WSL 发行版名称
# D:\wsl-backup\ubuntu.tar 是导出的备份包
wsl --export Ubuntu D:\wsl-backup\ubuntu.tar


# 5. 把刚才导出的 ubuntu.tar 重新导入为一个新的 WSL 发行版
# Ubuntu-D 是新发行版名称
# D:\wsl\Ubuntu-D 是新 WSL 的存放位置
# D:\wsl-backup\ubuntu.tar 是导入来源
# --version 2 表示使用 WSL2
wsl --import Ubuntu-D D:\wsl\Ubuntu-D D:\wsl-backup\ubuntu.tar --version 2


# 6. 把新的 Ubuntu-D 设置成默认 WSL
# 以后你直接输入 wsl，默认进入 Ubuntu-D
wsl --set-default Ubuntu-D

这里我没有立刻删除旧的 Ubuntu。更稳妥的做法是先保留旧环境几天，确认新环境网络、用户、Python、项目都正常，再执行：

1
wsl --unregister Ubuntu

注意，wsl --unregister 是删除发行版，不是简单取消注册。执行后旧 Ubuntu 的 Linux 文件系统会消失，所以不要急着用。

五、处理 .wslconfig 配置问题

5.1 出现的配置警告

在迁移 WSL 的过程中，曾经出现过一些配置警告，例如：

1
2
3
experimental.useWindowsDnsCache 中的键未知
使用镜像网络模式时，localhostForwarding 设置无效
无法配置网络 networkingMode Mirrored，回退到 networkingMode None

这些提示主要和 Windows 用户目录下的 .wslconfig 配置文件有关。

5.2 .wslconfig 的作用

.wslconfig 是 Windows 侧用于配置 WSL2 全局行为的文件，通常位于：C:\Users\你的用户名\.wslconfig

它可以配置 WSL2 的内存、CPU、交换空间、网络模式等参数，例如：

1
2
3
4
[wsl2]
memory=18GB
processors=4
swap=8GB

可以理解为：.wslconfig 是Windows 给 WSL2 设置运行资源和网络规则的配置文件

5.3 迁移后遇到的 DNS 问题

WSL 迁移完成后，曾经遇到过 DNS 问题。

具体表现是：

  1. 可以正常进入 WSL
  2. 但是访问 GitHub 或 HuggingFace 失败

例如执行：

1
2
curl -I https://github.com
curl -I https://huggingface.co

可能无法正常返回结果。克隆项目也没有网络。

我们先查看配置文件：

1
cat /etc/wsl.conf

当前输出的内容是：

1
2
3
4
5
6
7
8
[boot]
systemd=true

[user]
default=like

[network]
generateResolvConf = false

这里的关键是：

1
generateResolvConf = false

它表示 WSL 不自动生成 /etc/resolv.conf。

resolv.conf 可以理解为 Linux 的“电话簿”，程序访问 github.com 时，需要先通过它找到对应 IP。如果这个电话簿配置不对，网络就会表现为域名解析失败。

再看 /etc/resolv.conf 指向哪里：

1
2
ls -l /etc/resolv.conf
readlink -f /etc/resolv.conf

当前结果是：

1
2
/etc/resolv.conf -> ../run/systemd/resolve/stub-resolv.conf
/run/systemd/resolve/stub-resolv.conf

这说明当前 DNS 解析交给了 systemd-resolved。因此不用直接手改 /etc/resolv.conf，而是给 systemd-resolved 新增一个配置文件。

具体操作是在 WSL 里执行：

1
2
3
4
5
6
# 创建 systemd-resolved 的额外配置目录
# -p 表示目录不存在就创建，已经存在也不报错
sudo mkdir -p /etc/systemd/resolved.conf.d

# 用 nano 编辑器新建或打开 DNS 配置文件
sudo nano /etc/systemd/resolved.conf.d/wsl-dns.conf

如果不熟悉 nano，打开后把下面内容粘贴进去：

1
2
3
4
[Resolve]
DNS=1.1.1.1 8.8.8.8
FallbackDNS=223.5.5.5 114.114.114.114
DNSStubListener=yes

然后按 Ctrl + O 保存，按回车确认文件名，再按 Ctrl + X 退出。

在 WSL 里重启 DNS 服务：

1
sudo systemctl restart systemd-resolved

如果提示没有 systemd，说明你的 WSL 没启用 systemd。但这次环境里 /etc/wsl.conf 已经有：

1
2
[boot]
systemd=true

所以可以使用 systemctl。

最后验证：

1
2
3
getent hosts github.com
curl -I https://github.com
curl -I https://huggingface.co

当前测试结果能返回：

1
2
HTTP/2 200
HTTP/2 200

这说明 DNS 和 HTTPS 访问都正常。

总结

这次配置的核心思路是：在 Windows 上保留日常使用体验，同时用 WSL2 提供 Linux 项目的运行环境。

WSL 适合运行 GitHub 上默认面向 Linux 的项目，而把 WSL 迁移到 D 盘，则是为了让项目代码、依赖环境和下载数据主要占用 D 盘，避免 C 盘空间被慢慢占满。

后续开发时，推荐把项目放在 WSL 的 /home 目录下，再用 VS Code 的 WSL 模式打开。这样既能用熟悉的 VS Code 修改代码，又能在 Linux 环境中安装依赖、运行和调试项目。

简单来说，就是：

1
2
3
Windows 负责日常使用和编辑界面；
WSL 负责 Linux 环境和项目运行；
D 盘负责承载主要项目和依赖空间。

这种方式兼顾了使用方便、环境稳定和磁盘空间管理。