如何搭建 WSL 开发环境并完成第一次构建与部署？-开发者社区

如何搭建 WSL 开发环境并完成第一次构建与部署？

【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL

如果你要在 Windows 上从源码构建 Windows Subsystem for Linux（WSL），并把构建出的包安装到本机（或 Hyper-V 虚拟机）上跑第一轮测试，本文按开发文档给出一条可执行路径：安装构建依赖 → 生成解决方案并构建 → 部署 MSI → 运行首次测试。适用环境是 Windows（x64 或 ARM64），面向需要构建和修改 WSL 的开发者；普通用户直接安装 WSL 只需在 Windows 命令行运行wsl --install（见 README），不走本流程。

准备构建环境

所有前置依赖可以由一个脚本自动安装。在仓库根目录的 PowerShell 中运行：

tools\setup-dev-env.ps1

该脚本基于 WinGet Configuration，会安装 Developer Mode、CMake、Visual Studio 2022 以及.vsconfig中定义的工作负载。它先通过 vswhere 检测本机已安装的 VS 2022，已安装时选用与版本匹配的配置文件（Community / Professional / Enterprise 分别对应 .config 目录下的configuration.winget、configuration.vsProfessional.winget、configuration.vsEnterprise.winget）；未检测到 VS 2022 时默认安装 Community。脚本末尾会直接提示下一步命令：

cmake . cmake --build . -- -m

如果偏好手动安装，需要：

CMake >= 3.25，可用winget install Kitware.CMake安装
Visual Studio 2022 及所需组件：通过 VS Installer → More → Import configuration 导入.vsconfig，或执行winget install Microsoft.VisualStudio.2022.Community --override "--wait --quiet --config .vsconfig"
在 Windows 设置中启用 Developer Mode，或者用管理员权限运行构建——符号链接支持需要两者之一

手动运行时需显式启用 WinGet Configuration 功能，再指向仓库内的配置文件：

winget configure --enable winget configure -f .config/configuration.winget # Community（默认） winget configure -f .config/configuration.vsProfessional.winget # Professional winget configure -f .config/configuration.vsEnterprise.winget # Enterprise

ARM64 机器的额外要求

在 ARM64 Windows 上构建时，WiX 工具集（wix.exe）是 x64 二进制文件，需要x64 .NET 6.0 运行时，仅有 ARM64 .NET 运行时不够。按开发文档在 PowerShell 中安装：

# Download the official dotnet-install script Invoke-WebRequest -Uri "https://dot.net/v1/dotnet-install.ps1" -OutFile "$env:TEMP\dotnet-install.ps1" # Install the x64 .NET 6.0 runtime powershell -ExecutionPolicy Bypass -File "$env:TEMP\dotnet-install.ps1" -Channel 6.0 -Runtime dotnet -Architecture x64 -InstallDir "C:\Program Files\dotnet\x64"

然后设置DOTNET_ROOT_X64环境变量使运行时可被发现：

# Set for the current session $env:DOTNET_ROOT_X64 = "C:\Program Files\dotnet\x64" # Set permanently for your user [System.Environment]::SetEnvironmentVariable("DOTNET_ROOT_X64", "C:\Program Files\dotnet\x64", "User")

环境变量生效后，可能需要重启 VS Code 或新开终端才能被构建工具识别。

执行第一次构建

克隆仓库后，在仓库根目录生成 Visual Studio 解决方案：

cmake .

这会生成wsl.sln，之后可以用 Visual Studio 打开构建，也可以在命令行构建：

cmake --build .

按需附加构建参数（来自开发文档）：

参数	用途
`cmake . -A arm64`	构建 ARM64 包
`cmake . -DCMAKE_BUILD_TYPE=Release`	Release 构建，配合`cmake --build . --config Release`
`cmake . -DBUILD_BUNDLE=TRUE`	构建 bundle msix 包，要求先完成一次 ARM64 构建

可选：加快「构建—部署」迭代

频繁重复构建部署时，把 UserConfig.cmake.sample 复制为UserConfig.cmake：

copy UserConfig.cmake.sample UserConfig.cmake

再取消其中这一行的注释：

# set(WSL_DEV_BINARY_PATH "C:/wsldev")

这会改变构建逻辑，生成体积更小、安装更快的开发包（样例文件注明：.vhd文件无法通过符号链接/硬链接挂载，脚本内部改用复制，并对只读 VHD 用icacls.exe授予 Everyone 只读权限）。同一文件还提供两个可选开关：

set(WSL_BUILD_THIN_PACKAGE true)：构建更小的「thin」MSI 包
set(WSL_POST_BUILD_COMMAND "powershell;-ExecutionPolicy;Bypass;-NoProfile;-NonInteractive;./tools/deploy/deploy-to-host.ps1")：每次构建完成后自动把包部署到本机

部署构建产物

构建完成后，MSI 包位于bin\<platform>\<target>\wsl.msi；文档示例中平台与配置写作x64和debug（如bin\x64\debug\），ARM64 Release 构建则对应bin\arm64\Release\。

方式一：直接安装 MSI

用系统安装器安装bin\<platform>\<target>\wsl.msi即可。

方式二：部署脚本（推荐）

powershell tools\deploy\deploy-to-host.ps1

deploy-to-host.ps1 声明#Requires -RunAsAdministrator，需在管理员 PowerShell 中运行。脚本默认安装 Debug 包（bin\<platform>\Debug\wsl.msi，可用-BuildType Release切换），先把符号链接解析为真实路径（msiexec 不接受符号链接），再执行msiexec.exe /i <包路径> /qn /norestart静默安装且不重启。判断结果看脚本输出：成功时打印Package <路径> installed successfully；失败时打印Failed to install package: <退出码>并以退出码 1 结束。

可选：部署到 Hyper-V 虚拟机

powershell tools\deploy\deploy-to-vm.ps1 -VmName <vm> -Username <username> -Password <password>

deploy-to-vm.ps1 会创建到虚拟机的 PowerShell 会话，把bin/<platform>/<BuildType>/wsl.msi复制到虚拟机后远程执行同样的msiexec静默安装。把<vm>、<username>、<password>替换为你的虚拟机名与登录凭据；-Platform支持X64（默认）或arm64。

验证部署：运行第一轮测试

部署完成后，用构建输出目录中的test.bat运行单元测试。完整测试量很大，文档推荐先跑一个合理子集：

bin\x64\debug\test.bat /name:*UnitTest*

按你的实际平台与构建配置替换目录（例如 ARM64 Release 为bin\arm64\Release\test.bat）。运行单个测试用例的格式为test.bat /name:<class>::<test>，文档示例：

bin\x64\debug\test.bat /name:UnitTests::UnitTests::ModernInstall

其他选项：

-Version 1：在 WSL1 上运行测试，例如bin\x64\debug\test.bat -Version 1
首次运行测试后，可把test_distro设为默认发行版，之后加-f跳过包安装以加速测试（前提是test_distro确实已是默认 WSL 发行版）：

wsl --set-default test_distro bin\x64\debug\test.bat /name:*UnitTest* -f

测试基于 TAEF 框架执行，test/README.md 给出了TE.exe的完整参数：/list列出已加载测试、/name:支持*和?通配符筛选、/inproc在 TE.exe 进程内执行以便调试。调试时test.bat还支持/attachdebugger（自动附加 WinDbgX，需已安装 WinDbg）、/waitfordebugger（等待手动附加）、/breakonfailure（首个测试失败时中断）；通用调试方法见 debugging 文档。

限制与边界

符号链接支持要求 Developer Mode 或管理员权限构建，二者至少要满足其一，否则构建可能失败。
bundle msix（-DBUILD_BUNDLE=TRUE）必须先行完成 ARM64 构建，仅 x64 构建无法产出。
本流程的「部署」指把自构建包装到开发机或测试虚拟机上验证；生产分发应使用官方渠道，自构建包不面向最终用户。
若后续要提交代码，PR 合并前必须通过 clang-format：powershell .\FormatSource.ps1 -ModifiedOnly $false，或先执行cmake .再运行tools\SetupClangFormat.bat启用提交前自动检查，检查行为由UserConfig.cmake中的WSL_PRE_COMMIT_MODE控制（warn默认 /error阻断提交 /fix自动修复并重新暂存）。