WSLg源码构建教程:从Docker构建系统发行版到VHD部署的5步完整流程
WSLg源码构建教程:从Docker构建系统发行版到VHD部署的5步完整流程
这是一份面向新手的 WSLg 源码构建教程:使用 Docker 从源码编译 WSLg 系统发行版(system distro),并导出为 VHD 部署到 Windows。WSLg 是 Windows 子系统 Linux 的 GUI 支持层,让 X11/Wayland 图形应用在 Windows 上原生集成运行。跟着本文操作,你将拥有一个可自定义的私有系统发行版。
先搞懂:WSLg 与"系统发行版"是什么?
在开始构建前,先花一分钟理解目标产物。WSLg 的核心是一个名为系统发行版(system distro)的容器化 Linux 环境,其中运行着三个关键组件:
| 组件 | 作用 |
|---|---|
| Weston(Wayland 合成器) | WSLg 的心脏,负责把 Linux 应用窗口通过 RDP 传输到 Windows |
| XWayland | 让传统 X11 应用也能运行 |
| PulseAudio | 提供音频输入/输出 |
系统发行版最终被打包成一个 VHD 虚拟硬盘,Windows 以只读方式加载它,并将 Weston、XWayland、PulseAudio 的通信 socket 投射进你的用户发行版(如 Ubuntu)。下图展示了完整的 WSLg 架构:
构建完成后,你就能替换微软预发布的 VHD,运行自己编译的版本。
前置准备:一键搭建 Docker 构建环境
整个构建在 Linux 或 WSL 2 环境中进行,只需 Docker 和 Go(后者用于 tar2ext4 转换工具):
sudo apt-get update
sudo apt install docker.io golang-go
sudo dockerd
💡 建议直接在 WSL 2 的 Ubuntu 里操作,这样构建完的 VHD 可以立刻部署验证。
第一步:克隆 WSLg 主仓库
git clone https://gitcode.com/gh_mirrors/ws/wslg wslg
仓库结构很清晰,与本教程直接相关的文件:
- Dockerfile —— 核心构建脚本,多阶段编译所有组件
- build-and-export.sh —— 一键构建 + 导出 + VHD 转换
- CONTRIBUTING.md —— 官方构建说明
- WSLGd/main.cpp —— 守护进程源码(负责拉起 Weston 并监控重启)
第二步:准备 vendor 源码依赖
Dockerfile 假设依赖源码位于 wslg/vendor/ 目录下,需要克隆 5 个子项目(注意使用 working 分支,main 分支只是上游同步点):
git clone https://github.com/microsoft/FreeRDP-mirror wslg/vendor/FreeRDP -b working
git clone https://github.com/microsoft/weston-mirror wslg/vendor/weston -b working
git clone https://github.com/microsoft/PulseAudio-mirror wslg/vendor/pulseaudio -b working
git clone https://github.com/microsoft/DirectX-Headers.git wslg/vendor/DirectX-Headers-1.0 -b v1.608.0
git clone https://gitlab.freedesktop.org/mesa/mesa.git wslg/vendor/mesa -b mesa-23.1.0
各组件分工:
- FreeRDP —— Weston 的 RDP 服务端,负责协议编解码
- Weston —— 启用了 RAIL/VAIL 远程应用模式的新 RDP 后端
- PulseAudio —— 附带 RDP 音频 sink/source 插件
- Mesa —— 只启用
swrast,d3d12两个 Gallium 驱动(见 Dockerfile 第 240-245 行) - DirectX-Headers —— D3D12 图形加速所需的头文件
第三步:Docker 构建系统发行版镜像
推荐直接使用仓库自带脚本,它会自动从 git 版本推导各组件版本号并传入 --build-arg:
cd wslg
./build-and-export.sh
如果想手动执行,build-and-export.sh 的本质是这条命令(7 个 --build-arg 缺一不可,Dockerfile 开头会校验并快速失败,避免版本号 <unknown> 被烤进 /etc/versions.txt):
sudo docker build -f Dockerfile -t system-distro-x64 . \
--build-arg WSLG_VERSION="$(./devops/get-nuget-version.sh -Beta)" \
--build-arg WSLG_COMMIT="$(git rev-parse HEAD)" \
--build-arg WSLG_ARCH=x86_64 \
--build-arg DIRECTX_HEADERS_VERSION="$(git -C vendor/DirectX-Headers-1.0 rev-parse HEAD)" \
--build-arg FREERDP_COMMIT="$(git -C vendor/FreeRDP rev-parse HEAD)" \
--build-arg MESA_VERSION="$(git -C vendor/mesa rev-parse HEAD)" \
--build-arg PULSEAUDIO_COMMIT="$(git -C vendor/pulseaudio rev-parse HEAD)" \
--build-arg WESTON_COMMIT="$(git -C vendor/weston rev-parse HEAD)"
构建分两个阶段(见 Dockerfile):
- build-env 阶段:基于 Azure Linux 3.0 安装编译器与图形栈依赖,依次编译 DirectX-Headers、Mesa、PulseAudio、FreeRDP、rdpapplist 虚拟通道插件、Weston(
-Dbackend-default=rdp,只保留 RDP 后端)、WSLGd 守护进程 - runtime 阶段:全新基础镜像 + 最小运行时依赖,从 dev 阶段拷入编译产物,并写入 config/weston.ini、config/wsl.conf 等配置,容器启动命令即
/usr/bin/WSLGd
⚙️ 构建调试版:在命令末尾追加
--build-arg SYSTEMDISTRO_DEBUG_BUILD=true,产物会内嵌 gdb、vim 等调试工具,且保留全部调试符号。
第四步:导出容器并转换为 VHD
Docker 镜像不能直接被 Windows 加载,需要导出为 tar 再用 tar2ext4(来自 hcsshim)转成 ext4 VHD:
# 导出容器文件系统
sudo docker export "$(sudo docker create system-distro-x64)" > system_x64.tar
# 转换为 VHD(CI 固定使用 v0.13.0 保证可复现)
go run github.com/Microsoft/hcsshim/cmd/tar2ext4@v0.13.0 -vhd -i system_x64.tar -o system.vhd
执行完成后,当前目录就会出现 system.vhd——这就是你的 WSLg 系统发行版成品。
第五步:部署私有 VHD 到 Windows
把生成的 system.vhd 复制到 Windows(如 C:\Files\system.vhd),然后编辑用户目录下的 .wslconfig(C:\Users\MyUser\.wslconfig):
[wsl2]
systemDistro=C:\\Files\\system.vhd
以管理员身份重启 WSL 使配置生效:
wsl --shutdown
再次启动任意用户发行版时,Windows 就会加载你私有的 VHD 而不是微软发布的版本。之后执行 wsl --update 只会更新官方版本,你的私有发行版不受影响,随时可切换回退。
验证与常见问题排查
部署后可以用以下命令进入系统发行版检查(每个用户发行版都配有一个独立的系统发行版实例):
wsl --system -d Ubuntu
进入后验证 Weston 与 PulseAudio 是否正常运行:
ps -ax | grep weston
ps -ax | grep pulse
cat /etc/versions.txt # 确认各组件版本号已正确写入
🔍 常见坑位:
- 7 个 build-arg 报错缺失:说明手动构建漏传参数,直接用 build-and-export.sh 可避免
- 版本号显示
dev:本地浅克隆或缺少 tag 时的正常回退(见 devops/get-nuget-version.sh) - 改了系统发行版重启后丢失:这是设计行为——VHD 以只读方式挂载,任何运行时修改重启即丢弃。要持久化请修改 Dockerfile 后重新构建
进阶:构建 Windows 侧 mstsc 插件
WSLg 的完整闭环还包含 Windows 侧的 WSLDVCPlugin,它通过自定义 RDP 通道枚举 Linux GUI 应用并在开始菜单创建快捷方式。可以用 Visual Studio 打开 WSLDVCPlugin.sln 编译,再通过 RegisterWSLPlugin.reg 注册到 mstsc,配合你的私有 VHD 形成完全自托管的 WSLg 环境。
总结
| 步骤 | 关键命令/文件 | 产物 |
|---|---|---|
| 环境准备 | Docker + Go | 构建环境 |
| 克隆仓库与 vendor 源码 | git clone ×6 |
完整源码树 |
| Docker 多阶段构建 | Dockerfile | system-distro-x64 镜像 |
| 导出 + 转换 VHD | docker export + tar2ext4 |
system.vhd |
| 部署 | .wslconfig + wsl --shutdown |
私有系统发行版生效 |
至此,你已经走完了 WSLg 从源码到 VHD 的完整构建部署链路。可以在此基础上修改 config/ 中的配置、替换 Weston 或 PulseAudio 的补丁,打造完全属于自己的 Linux GUI 子系统 🚀

