WSL 中的進階設定組態

發行項
01/17/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 發行版本的子系統完全停止執行並重新啟動，才能顯示組態設定更新。關閉發行版本殼層的「所有」執行個體之後，這通常需要大約 8 秒的時間。

如果您啟動發行版本 (例如 Ubuntu)，請修改組態檔、關閉發行版本，然後重新啟動，您可能會假設您的設定變更已立即生效。目前情況並非如此，因為子系統仍然可以執行。您必須等候子系統停止然後再重新啟動，才能提供足夠的時間來挑選您的變更。您可以使用 PowerShell 搭配命令 wsl --list --running，在關閉之後檢查 Linux 發行版本 (Shell) 是否仍在執行中。如果沒有發行版本正在執行，您會收到回應：「沒有執行中的發行版本。」您現在可以重新啟動發行版本，以查看套用的設定更新。

此命令 wsl --shutdown 是重新啟動 WSL 2 發行版本的快速路徑，但會關閉所有執行中的發行版本，因此請妥善使用。您也可以使用 wsl --terminate <distroName> 來終止立即執行的特定散發。

wsl.conf

針對在 WSL 1 或 WSL 2 上執行的每個 Linux 散發套件，使用 wsl.conf 設定本機設定。

以 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 發行版本預設會執行「systemd」(包括 Ubuntu)，而 WSL 最近已新增此系統/服務管理員的支援，讓 WSL 更類似於在裸機電腦上使用您慣用的 Linux 發行版本。您需要 0.67.6+ 版的 WSL 才能啟用 systemd。使用命令 wsl --version 檢查您的 WSL 版本。如果您需要更新，則可以在 Microsoft Store 中抓取最新版本的 WSL。在部落格公告中深入了解。

若要啟用 systemd，請使用 sudo 在文字編輯器中開啟您的 wsl.conf 檔案，以取得系統管理員權限，並將這幾行新增至 /etc/wsl.conf：

[boot]
systemd=true

接著，您必須使用 wsl.exe --shutdown 從 PowerShell 關閉 WSL 發行版本，以重新啟動您的 WSL 執行個體。發行版本重新啟動之後，systemd 應該正在執行。您可以使用命令 systemctl list-unit-files --type=service 進行確認，這會顯示服務的狀態。

自動掛接設定

wsl.conf 區段卷標： [automount]

索引鍵	value	預設值	附註
「已啟用」	boolean	true	`true` 會使固定磁碟機 (亦即 `C:/` 或 `D:/`) 使用 DrvFs自動掛接在 `/mnt` 下方。 `false` 表示磁碟機不會自動掛接，但您仍然可以手動或透過 `fstab` 來掛接。
mountFsTab	boolean	true	`true` 會將 `/etc/fstab` 設定為在 WSL 啟動時處理。 /etc/fstab 是一個檔案，您可以在其中宣告其他檔案系統，例如 SMB 共用。因此，您可以在啟動時，在 WSL 中自動掛接這些檔案系統。
根	string	`/mnt/`	設定將自動掛接固定磁碟機的目錄。根據預設，這會設定為 `/mnt/`，因此您的 Windows 檔案系統 C 磁碟機會掛接至 `/mnt/c/`。如果您將 `/mnt/` 變更為 `/windir/`，您應該會看到固定 C 磁碟機掛接至 `/windir/c`。
選項	以逗點分隔的值清單，例如 uid、gid 等，請參閱下方的自動掛接選項	空字串	自動掛接選項值如下所列，並附加至預設 DrvFs 掛接選項字串。只能指定 DrvFs 特定選項。

自動掛接選項會套用為所有自動掛接磁碟機的掛接選項。若只要變更特定磁碟機的選項，請改用 /etc/fstab 檔案。不支援掛接二進位檔通常會剖析成旗標的選項。如果您想要明確指定這些選項，必須在 /etc/fstab 中包含您要執行此動作的每個磁碟機。

自動掛接選項

為 Windows 磁碟機 (DrvFs) 設定不同的掛接選項，可以控制 Windows 檔案計算檔案許可權的方式。下列是可用的選項：

關鍵	描述	預設
uid	用於所有檔案擁有者的使用者識別碼	WSL 發行版本版本的預設使用者識別碼 (在第一次安裝時，此預設值為1000)
gid	用於所有檔案擁有者的群組識別碼	WSL 發行版本版本的預設群組識別碼 (在第一次安裝時，此預設值為1000)
umask	要排除所有檔案和目錄的權限八進位遮罩	022
fmask	要排除所有檔案的權限八進位遮罩	000
dmask	要排除所有目錄的權限八進位遮罩	000
中繼資料	是否將中繼資料新增至 Windows 檔案以支援 Linux 系統權限	停用
case	判斷被視為區分大小寫的目錄，以及以 WSL 建立的新目錄是否會設定旗標。如需選項的詳細說明，請參閱區分大小寫。選項包含 `off`、`dir` 或 `force`。	`off`

根據預設，WSL 會將 uid 和 gid 設定為預設使用者的值。例如，在 Ubuntu 中，預設使用者是 uid=1000、gid=1000。如果這個值用來指定不同的 gid 或 uid 選項，則會覆寫預設的使用者值。否則，一律會附加預設值。

使用者檔案建立模式遮罩 (umask) 會設定新建立檔案的權限。預設值為 022，只有您可以寫入資料，但任何人都可以讀取資料。值可以變更以反映不同的權限設定。例如，umask=077 會將權限變更為完全私人，其他使用者無法讀取或寫入資料。若要進一步指定權限，也可以使用 fmask (檔案) 和 dmask (目錄)。

注意

許可權遮罩會在套用至檔案或目錄之前，先執行邏輯 OR 作業。

什麼是 DrvFs？

DrvFs 是 WSL 的檔案系統外掛程式，其設計目的是支援 WSL 與 Windows 檔案系統之間的互通性。 DrvFs 可讓 WSL 在 /mnt 下以支援的檔案系統掛接磁碟機，例如 /mnt/c、/mnt/d 等。如需掛接 Windows 或 Linux 磁碟機或目錄時指定預設區分大小寫行為的詳細資訊，請參閱區分大小寫頁面。

網路設定

wsl.conf 區段卷標： [network]

索引鍵	value	預設值	附註
generateHosts	boolean	`true`	`true` 會設定 WSL 以產生 `/etc/hosts`。 `hosts` 檔案包含主機名稱對應 IP 位址的靜態對應。
generateResolvConf	boolean	`true`	`true` 會設定 WSL 以產生 `/etc/resolv.conf`。 `resolv.conf` 包含DNS 清單，可以將指定主機名稱解析為其 IP 位址。
hostname	string	Windows 主機名稱	設定要用於 WSL 發行版本的主機名稱。

互通性設定

wsl.conf 區段卷標： [interop]

這些選項可在測試人員組建 17713 和更新版本中使用。

索引鍵	value	預設值	附註
「已啟用」	boolean	`true`	設定此機碼將決定 WSL 是否支援啟動 Windows 程序。
appendWindowsPath	boolean	`true`	設定此機碼將決定 WSL 是否會將 Windows 路徑元素新增至 $PATH 環境變數。

使用者設定

wsl.conf 區段卷標： [user]

這些選項可在組建 18980 和更新版本中取得。

索引鍵	value	預設值	附註
預設值	string	第一次執行時建立的初始使用者名稱	設定此金鑰會指定第一次啟動 WSL 工作階段時要執行的使用者。

開機設定

開機設定僅適用於 Windows 11 和 Server 2022。

wsl.conf 區段卷標： [boot]

索引鍵	value	預設值	附註
命令	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

在 WSL 上執行的所有已安裝散發套件上，使用 .wslconfig 設定全域設定。

.wslconfig 檔案預設不存在。它必須建立並儲存在您的 %UserProfile% 目錄中，才能套用這些組態設定。
用來全域設定以 WSL 2 版本執行的所有已安裝 Linux 發行版本之間的設定。
僅適用於 WSL 2所執行的發行版本。以 WSL 1 執行的發行版本不會受到此設定的影響，因為其不是以虛擬機器執行。
若要進入您的 %UserProfile% 目錄，請在 PowerShell 中，使用 cd ~ 來存取主目錄 (通常是您的使用者設定檔 C:\Users\<UserName>)，或者您可以開啟 Windows 檔案總管並在網址列中輸入 %UserProfile%。目錄路徑看起來應該類似於：C:\Users\<UserName>\.wslconfig。

WSL 會偵測這些檔案是否存在、讀取內容，並在每次啟動 WSL 時自動套用組態設定。如果檔案遺失或格式不正確 (標記格式不正確)，WSL 會繼續正常啟動，而不會套用組態設定。

.wslconfig 的組態設定

.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]

索引鍵	value	預設值	附註
核心 (kernel)	path	Microsoft 建置核心提供的收件匣	自訂 Linux 核心的絕對 Windows 路徑。
記憶體	size	Windows 上總記憶體的 50%	要指派給 WSL 2 VM 的記憶體量。
處理器	數值	Windows 上相同的邏輯處理器數目	要指派給 WSL 2 VM 的邏輯處理器數目。
localhostForwarding	boolean	`true`	布林值，指定 WSL 2 VM 中繫結至萬用字元或 localhost 的連接埠是否應該可透過 `localhost:port` 從主機連線。
kernelCommandLine	string	Blank	其他核心命令列引數。
safeMode	boolean	`false`	在「安全模式」中執行 WSL 會停用許多功能，而目的是用來復原處於不良狀態的發行版本。僅適用於 Windows 11 和 WSL 0.66.2+版。
swap	size	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	boolean*	`true`	可開啟或關閉 WSL 中 GUI 應用程式 (WSLg) 支援的布林值。僅適用於 Windows 11。
debugConsole	boolean*	`false`	可開啟輸出主控台視窗的布林值，顯示 WSL 2 發行版本執行個體啟動時 `dmesg` 的內容。僅適用於 Windows 11。
nestedVirtualization	boolean*	`true`	可開啟或關閉巢狀虛擬化的布林值，讓其他巢狀 VM 能夠在 WSL 2 內執行。僅適用於 Windows 11。
vmIdleTimeout	number*	`60000`	VM 在關閉之前閒置的毫秒數。僅適用於 Windows 11。
dnsProxy	bool	true	僅適用於 networkingMode = NAT。布爾值，通知 WSL 將 Linux 中的 DNS 伺服器設定為主機上的 NAT。將設定為 false 會將 DNS 伺服器從 Windows 鏡像到 Linux。
networkingMode**	字串	NAT	如果值為 `mirrored`，則這會開啟鏡像網路模式。預設或無法辨識的字串會導致 NAT 網路。
防火牆**	bool	true	將此設定為 true 可讓 Windows 防火牆規則，以及 Hyper-V 流量專屬的規則來篩選 WSL 網路流量。
dnsTunneling**	bool	false	變更將 DNS 要求從 WSL 代理至 Windows 的方式
autoProxy*	bool	false	強制 WSL 使用 Windows 的 HTTP Proxy 資訊

具有 path 值的項目必須是具有逸出反斜線的 Windows 路徑，例如：C:\\Temp\\myCustomKernel

具有 size 值的項目必須是大小，後面接著單位，例如 8GB 或 512MB。

在值類型之後具有 * 的項目只能在 Windows 11 上使用。

在實值類型之後具有 ** 的專案需要 Windows 11 版本 22H2 或更高版本。

實驗性設定

這些設定是實驗性功能的選擇預覽，我們的目標是在未來設為預設值。

.wslconfig 區段卷標： [experimental]

設定名稱	值	預設	備註
`autoMemoryReclaim`	string	停用	偵測閒置 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 Proxy 資訊的時間長度。如果 Proxy 設定在此時間之後解析，則必須重新啟動 WSL 執行個體，才能使用擷取的 Proxy 設定。
`ignoredPorts`**	string	null	只有在 `wsl2.networkingMode` 設定為 `mirrored` 時才適用。指定 Linux 應用程式可以繫結至哪些連接埠，即使該連接埠用於 Windows 也一樣。這可讓應用程式完全在Linux內接聽流量的埠，因此即使該埠用於Windows上的其他用途，也不會封鎖這些應用程式。例如，WSL 將允許系結至適用於 Docker Desktop 的 Linux 連接埠 53，因為它只會接聽 Linux 容器內的要求。應該以逗號分隔清單格式化，例如： `3000,9000,9090`
`hostAddressLoopback`**	bool	false	只有在 `wsl2.networkingMode` 設定為 `mirrored` 時才適用。當設定為 `True`時，會允許容器連線到主機，或主機以指派給主機的IP位址連線到容器。 `127.0.0.1`一律可以使用回送位址，此選項也允許使用所有額外指派的本機 IP 位址。僅支援指派給主機的IPv4位址。