WSL 中的高级设置配置

项目
02/03/2024

wsl.conf 和 .wslconfig 文件用于针对每个发行版 (wsl.conf) 和全局跨所有 WSL 2 发行版 (.wslconfig) 配置高级设置选项。本指南将介绍每个设置选项、何时使用每种文件类型、存储文件的位置、示例设置文件和提示。

wsl.conf 和 .wslconfig 之间有什么差别？

可以为已安装的 Linux 发行版配置设置，使它们在你每次启动 WSL 时自动应用，有两种方法：

.wslconfig 用于在 WSL 2 上运行的所有已安装发行版中配置全局设置。
wsl.conf 用于为在 WSL 1 或 WSL 2 上运行的每个 Linux 发行版按各个发行版配置本地设置。

这两种文件类型都用于配置 WSL 设置，但存储文件的位置、配置的范围、可配置的选项类型，以及运行发行版的 WSL 版本都会影响应选择的文件类型。

WSL 1 和 WSL 2 使用不同的体系结构运行，并会影响配置设置。 WSL 2 作为轻型虚拟机 (VM) 运行，因此请使用让你能够控制内存或处理器使用量的虚拟化设置（使用 Hyper-V 或 VirtualBox 的话可能会比较熟悉）。检查正在运行的 WSL 的版本。

配置更改的 8 秒规则

必须等到运行你的 Linux 发行版的子系统完全停止运行并重启，配置设置更新才会显示。这通常需要关闭发行版 shell 的所有实例后大约 8 秒。

如果启动分发版（例如 Ubuntu），请修改配置文件，关闭分发版，然后重启它，你可能会假设配置更改已立即生效。但当前情况并非如此，因为子系统可能仍在运行。在重启之前，必须等子系统停止，给它足够的时间来获取你的更改。可以通过使用 PowerShell 和以下命令来检查关闭 Linux 发行版 (shell) 后其是否仍在运行：wsl --list --running。如果分发版未运行，则会收到响应：“没有正在运行的分发版。”现在可以重启分发版，以查看应用的配置更新。

命令 wsl --shutdown 是重启 WSL 2 发行版的快速路径，但它会关闭所有正在运行的发行版，因此请谨慎使用。还可以使用 wsl --terminate <distroName> 来终止立即运行的特定发行版。

wsl.conf

使用 wsl.conf 为 WSL 1 或 WSL 2 上运行的每个 Linux 发行版按各个发行版配置本地设置。

作为 unix 文件存储在发行版的 /etc 目录中。
用于针对每个发行版配置设置。在此文件中配置的设置将仅应用于包含存储此文件的目录的特定 Linux 发行版。
可用于由 WSL 1 或 WSL 2 版本运行的发行版。
若要访问已安装的发行版的 /etc 目录，请使用发行版的命令行和 cd / 访问根目录，然后使用 ls 列出文件或使用 explorer.exe . 在 Windows 文件资源管理器中查看。该目录路径应类似于：/etc/wsl.conf。

注意

使用 wsl.conf 文件调整每个发行版设置的功能仅适用于 Windows 版本 17093 及更高版本。

wsl.conf 的配置设置

wsl.conf 文件会针对每个发行版配置设置。 （有关 WSL 2 发行版的全局配置，请参阅 .wslconfig）。

wsl.conf 文件支持四个部分：automount、network、interop 和 user。 （在 .ini 文件约定之后建模，密钥在 .gitconfig 文件等部分下声明。）有关存储 wsl.conf 文件位置的信息，请参阅 wsl.conf。

systemd 支持

许多 Linux 发行版（包括 Ubuntu）默认运行“systemd”，WSL 最近添加了对此系统/服务管理器的支持，因此 WSL 更类似于在裸机上使用你最爱的 Linux 发行版。需要 WSL 的 0.67.6+ 版本才能启用 systemd。使用命令 wsl --version 检查 WSL 版本。如果需要更新，可以在 Microsoft Store 中获取最新版本的 WSL。有关详细信息，请参阅博客公告。

若要启用 systemd，请使用 sudo 通过管理员权限在文本编辑器中打开 wsl.conf 文件，并将以下行添加到 /etc/wsl.conf：

[boot]
systemd=true

然后，需要通过 PowerShell 使用 wsl.exe --shutdown 来关闭 WSL 发行版以重启 WSL 实例。发行版重启后，systemd 应该就会运行了。可以使用 systemctl list-unit-files --type=service 命令进行确认，该命令会显示服务的状态。

自动装载设置

wsl.conf 节标签：[automount]

key	value	default	说明
enabled	boolean	是	`true` 导致固定驱动器（即 `C:/` 或 `D:/`）自动装载到 DrvFs 中的 `/mnt` 下。 `false` 表示驱动器不会自动装载，但你仍可以手动或通过 `fstab` 装载驱动器。
mountFsTab	boolean	是	`true` 设置启动 WSL 时要处理的 `/etc/fstab`。 /etc/fstab 是可在其中声明其他文件系统的文件，类似于 SMB 共享。因此，在启动时，可以在 WSL 中自动装载这些文件系统。
root	string	`/mnt/`	设置固定驱动器要自动装载到的目录。默认情况下，此项设置为 `/mnt/`，因此 Windows 文件系统 C 驱动器会装载到 `/mnt/c/`。如果将 `/mnt/` 更改为 `/windir/`，则你应会看到固定的 C 驱动器装载到 `/windir/c`。
选项	以逗号分隔的值的列表，例如 uid、gid 等，请参阅下面的自动装载选项	空字符串	下面列出了自动装载选项值，它们追加到了默认的 DrvFs 装载选项字符串中。只能指定特定于 DrvFs 的选项。

对于所有自动装载的驱动器，这些自动装载选项会应用为装载选项。若要仅更改特定驱动器的选项，请改用 /etc/fstab 文件。通常由装载二进制文件分析成标志的选项不受支持。若要显式指定这些选项，必须在 /etc/fstab 中包含要对其执行此操作的每个驱动器。

自动装载选项

为 Windows 驱动器 (DrvFs) 设置不同的装载选项可以控制为 Windows 文件计算文件权限的方式。可使用以下选项：

密钥	说明	默认
uid	用于所有文件的所有者的用户 ID	WSL 发行版的默认用户 ID（首次安装时，此项默认为 1000）
gid	用于所有文件的所有者的组 ID	WSL 发行版的默认组 ID（首次安装时，此项默认为 1000）
umask	要对所有文件和目录排除的权限的八进制掩码	022
fmask	要对所有文件排除的权限的八进制掩码	0.00
dmask	要对所有目录排除的权限的八进制掩码	0.00
metadata	是否将元数据添加到 Windows 文件以支持 Linux 系统权限	disabled
case	确定被视为区分大小写的目录以及使用 WSL 创建的新目录是否将设置标志。有关选项的详细说明，请参阅区分大小写。选项包括 `off`、`dir` 或 `force`。	`off`

默认情况下，WSL 会将 uid 和 gid 设置为默认用户的值。例如，在 Ubuntu 中，默认用户为 uid=1000，gid=1000。如果此值用于指定不同的 gid 或 uid 选项，则默认用户值将被覆盖。否则，将始终追加默认值。

用户文件创建模式掩码 (umask) 会为新创建的文件设置权限。默认值为 022，只有你可以写入数据，但任何人都可以读取数据。可以更改值以反映不同的权限设置。例如，umask=077 会将权限更改为完全私密，其他用户无法读取或写入数据。若要进一步指定权限，也可以使用 fmask（文件）和 dmask（目录）。

注意

权限掩码在应用到文件或目录之前通过一个逻辑或操作进行设置。

什么是 DrvFs？

DrvFs 是 WSL 的文件系统插件，旨在支持 WSL 和 Windows 文件系统之间的互操作。 DrvFs 支持 WSL 在 /mnt 下装载包含支持的文件系统的驱动器，例如 /mnt/c、/mnt/d 等。有关在装载 Windows 或 Linux 驱动器或目录时指定默认区分大小写行为的详细信息，请参阅区分大小写页。

网络设置

wsl.conf 节标签：[network]

key	value	default	说明
generateHosts	boolean	`true`	`true` 将 WSL 设置为生成 `/etc/hosts`。 `hosts` 文件包含主机名对应的 IP 地址的静态映射。
generateResolvConf	boolean	`true`	`true` 将 WSL 设置为生成 `/etc/resolv.conf`。 `resolv.conf` 包含能够将给定主机名解析为其 IP 地址的 DNS 列表。
hostname	string	Windows 主机名	设置要用于 WSL 发行版的主机名。

互操作设置

wsl.conf 节标签：[interop]

这些选项在预览体验成员内部版本 17713 和更高版本中可用。

key	value	default	说明
enabled	boolean	`true`	设置此键可确定 WSL 是否支持启动 Windows 进程。
appendWindowsPath	boolean	`true`	设置此键可确定 WSL 是否会将 Windows 路径元素添加到 $PATH 环境变量。

用户设置

wsl.conf 节标签：[user]

这些选项在版本 18980 及更高版本中可用。

key	value	default	说明
默认值	string	首次运行时创建的初始用户名	设置此键指定在首次启动 WSL 会话时以哪个用户身份运行。

启动设置

启动设置仅在 Windows 11 和 Server 2022 上可用。

wsl.conf 节标签：[boot]

key	value	default	说明
命令	string	""	你希望在 WSL 实例启动时运行的命令字符串。此命令以根用户身份运行。例如 `service docker start`。

示例 wsl.conf 文件

下面的 wsl.conf 示例文件演示了一些可用的配置选项。在此示例中，分发版为 Ubuntu-20.04，文件路径为 \\wsl.localhost\Ubuntu-20.04\etc\wsl.conf。

# Automatically mount Windows drive when the distribution is launched
[automount]

# Set to true will automount fixed drives (C:/ or D:/) with DrvFs under the root directory set above. Set to false means drives won't be mounted automatically, but need to be mounted manually or with fstab.
enabled = true

# Sets the directory where fixed drives will be automatically mounted. This example changes the mount location, so your C-drive would be /c, rather than the default /mnt/c. 
root = /

# DrvFs-specific options can be specified.  
options = "metadata,uid=1003,gid=1003,umask=077,fmask=11,case=off"

# Sets the `/etc/fstab` file to be processed when a WSL distribution is launched.
mountFsTab = true

# Network host settings that enable the DNS server used by WSL 2. This example changes the hostname, sets generateHosts to false, preventing WSL from the default behavior of auto-generating /etc/hosts, and sets generateResolvConf to false, preventing WSL from auto-generating /etc/resolv.conf, so that you can create your own (ie. nameserver 1.1.1.1).
[network]
hostname = DemoHost
generateHosts = false
generateResolvConf = false

# Set whether WSL supports interop processes like launching Windows apps and adding path variables. Setting these to false will block the launch of Windows processes and block adding $PATH environment variables.
[interop]
enabled = false
appendWindowsPath = false

# Set the user when launching a distribution with WSL.
[user]
default = DemoUser

# Set a command to run when a new WSL instance launches. This example starts the Docker container service.
[boot]
command = service docker start

.wslconfig

使用 .wslconfig 为 WSL 上运行的所有已安装的发行版配置全局设置。

默认情况下，.wslconfig 文件不存在。它必须创建并存储在%UserProfile%目录中才能应用这些配置设置。
用于在作为 WSL 2 版本运行的所有已安装的 Linux 发行版中全局配置设置。
只能用于 WSL 2 运行的发行版。作为 WSL 1 运行的发行版不受此配置的影响，因为它们不作为虚拟机运行。
要访问 %UserProfile% 目录，请在 PowerShell 中使用 cd ~ 访问主目录（通常是用户配置文件 C:\Users\<UserName>），或者可以打开 Windows 文件资源管理器并在地址栏中输入 %UserProfile%。该目录路径应类似于：C:\Users\<UserName>\.wslconfig。

WSL 将检测这些文件是否存在，读取内容，并在每次启动 WSL 时自动应用配置设置。如果文件缺失或格式错误（标记格式不正确），则 WSL 将继续正常启动，而不应用配置设置。

.wsl.conf 的配置设置

.wslconfig 文件为使用 WSL 2 运行的所有 Linux 发行版全局配置设置。 （有关针对发行版配置的信息，请参阅 wsl.conf）。

有关 .wslconfig 文件的存储位置的信息，请参阅 .wslconfig。

注意

使用 .wslconfig 进行全局配置的选项仅适用于在 Windows 版本 19041 及更高版本中作为 WSL 2 运行的发行版。请记住，可能需要运行 wsl --shutdown 来关闭 WSL 2 VM，然后重启 WSL 实例以使这些更改生效。

此文件可以包含以下选项，它们会影响为任何 WSL 2 发行版提供支持的 VM：

主要 WSL 设置

.wslconfig 节标签：[wsl2]

key	value	default	说明
内核 (kernel)	path	Microsoft 内置内核提供的收件箱	自定义 Linux 内核的绝对 Windows 路径。
内存	size	Windows 上总内存的 50%	要分配给 WSL 2 VM 的内存量。
处理器	number	Windows 上相同数量的逻辑处理器	要分配给 WSL 2 VM 的逻辑处理器数量。
localhostForwarding	boolean	`true`	一个布尔值，用于指定绑定到 WSL 2 VM 中的通配符或 localhost 的端口是否应可通过 `localhost:port` 从主机连接。
kernelCommandLine	string	空白	其他内核命令行参数。
safeMode	boolean	`false`	在“安全模式”中运行 WSL，这会禁用许多功能，应用于恢复处于错误状态的发行版。仅适用于 Windows 11 和 WSL 版本 0.66.2+。
swap	大小	Windows 上 25% 的内存大小四舍五入到最接近的 GB	要向 WSL 2 VM 添加的交换空间量，0 表示无交换文件。交换存储是当内存需求超过硬件设备上的限制时使用的基于磁盘的 RAM。
swapFile	path	`%USERPROFILE%\AppData\Local\Temp\swap.vhdx`	交换虚拟硬盘的绝对 Windows 路径。
pageReporting	boolean	`true`	默认的 `true` 设置使 Windows 能够回收分配给 WSL 2 虚拟机的未使用内存。
guiApplications	布尔*	`true`	一个布尔值，用于在 WSL 中打开或关闭对 GUI 应用程序 (WSLg) 的支持。仅适用于 Windows 11。
debugConsole	布尔*	`false`	一个布尔值，用于在 WSL 2 发行版实例启动时打开显示 `dmesg` 内容的输出控制台窗口。仅适用于 Windows 11。
nestedVirtualization	布尔*	`true`	用于打开或关闭嵌套虚拟化的布尔值，使其他嵌套 VM 能够在 WSL 2 中运行。仅适用于 Windows 11。
vmIdleTimeout	数量*	`60000`	VM 在关闭之前处于空闲状态的毫秒数。仅适用于 Windows 11。
dnsProxy	bool	true	仅适用于 networkingMode = NAT。布尔值，通知 WSL 将 Linux 中的 DNS 服务器配置为主机上的 NAT。设置为 false 会将 DNS 服务器从 Windows 镜像到 Linux。
networkingMode**	string	NAT	如果值为 `mirrored`，则会启用镜像网络模式。默认或无法识别的字符串会生成 NAT 网络。
firewall**	bool	是	如果设置为 true，则 Windows 防火墙规则以及特定于 Hyper-V 流量的规则可以筛选 WSL 网络流量。
dnsTunneling**	bool	false	更改将 DNS 请求从 WSL 代理到 Windows 的方式
autoProxy*	bool	false	强制 WSL 使用 Windows 的 HTTP 代理信息

具有 path 值的条目必须是带有转义反斜杠的 Windows 路径，例如：C:\\Temp\\myCustomKernel

具有 size 值的条目后面必须跟上大小的单位，例如 8GB 或 512MB。

值类型后带有 * 的条目仅在 Windows 11 中可用。

值类型后带有 ** 的条目需要 Windows 11 版本 22H2 或更高版本。

实验性设置

这些设置是试验性功能的选择加入预览，我们的目标是将来将其设为默认设置。

.wslconfig 节标签：[experimental]

设置名称	值	默认值	说明
`autoMemoryReclaim`	string	disabled	检测空闲 CPU 使用率后，自动释放缓存的内存。设置为 `gradual` 以慢速释放，设置为 `dropcache` 以立即释放缓存的内存。
`sparseVhd`	bool	false	如果设置为 true，则任何新创建的 VHD 将自动设置为稀疏。
`useWindowsDnsCache`**	bool	false	仅当 `wsl2.dnsTunneling` 设置为 true 时才适用。如果此选项设置为 false，则从 Linux 隧道传输的 DNS 请求将绕过 Windows 中的缓存名称，以始终将请求放在网络上。
`bestEffortDnsParsing`**	bool	false	仅当 `wsl2.dnsTunneling` 设置为 true 时才适用。如果设置为 true，Windows 将从 DNS 请求中提取问题并尝试解决该问题，从而忽略未知记录。
`initialAutoProxyTimeout`*	string	1000	仅当 `wsl2.autoProxy` 设置为 true 时才适用。配置启动 WSL 容器时，WSL 等待检索 HTTP 代理信息的时长（以毫秒为单位）。如果代理设置在此时间之后解析，则必须重启 WSL 实例才能使用检索到的代理设置。
`ignoredPorts`**	string	Null	仅当 `wsl2.networkingMode` 设置为 `mirrored` 时才适用。指定 Linux 应用程序可以绑定到哪些端口（即使该端口已在 Windows 中使用）。通过此设置，应用程序能够仅侦听 Linux 中的流量端口，因此即使该端口在 Windows 上用于其他用途，这些应用程序也不会被阻止。例如，WSL 将允许绑定到 Linux for Docker Desktop 中的端口 53，因为它只侦听来自 Linux 容器中的请求。应在逗号分隔列表中设置格式，例如：`3000,9000,9090`
`hostAddressLoopback`**	bool	false	仅当 `wsl2.networkingMode` 设置为 `mirrored` 时才适用。如果设置为 `True`，将会允许容器通过分配给主机的 IP 地址连接到主机，或允许主机通过此方式连接到容器。始终可以使用 `127.0.0.1` 环回地址，此选项也允许使用所有额外分配的本地 IP 地址。仅支持分配给主机的 IPv4 地址。