WSL 中的進階設定組態
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 | 預設值 | 附註 |
|---|---|---|---|
enabled |
boolean | true |
true 會使固定磁碟機 (亦即 C:/ 或 D:/) 使用 DrvFs自動掛接在 /mnt 下方。 false 表示磁碟機不會自動掛接，但您仍然可以手動或透過 fstab 來掛接。 |
mountFsTab |
boolean | true |
true 會將 /etc/fstab 設定為在 WSL 啟動時處理。 /etc/fstab 是一個檔案，您可以在其中宣告其他檔案系統，例如 SMB 共用。 因此，您可以在啟動時，在 WSL 中自動掛接這些檔案系統。 |
root |
字串 | /mnt/ |
設定將自動掛接固定磁碟機的目錄。 根據預設，這會設定為 /mnt/，因此您的 Windows 檔案系統 C 磁碟機會掛接至 /mnt/c/。 如果您將 /mnt/ 變更為 /windir/，您應該會看到固定 C 磁碟機掛接至 /windir/c。 |
options |
以逗點分隔的值清單，例如 uid、gid 等，請參閱下方的自動掛接選項 | 空字串 | 自動掛接選項值如下所列，並附加至預設 DrvFs 掛接選項字串。 只能指定 DrvFs 特定選項。 |
自動掛接選項會套用為所有自動掛接磁碟機的掛接選項。 若只要變更特定磁碟機的選項，請改用 /etc/fstab 檔案。 不支援掛接二進位檔通常會剖析成旗標的選項。 如果您想要明確指定這些選項，必須在 /etc/fstab 中包含您要執行此動作的每個磁碟機。
自動掛接選項
為 Windows 磁碟機 (DrvFs) 設定不同的掛接選項，可以控制 Windows 檔案計算檔案許可權的方式。 下列是可用的選項：
| 關鍵 | 描述 | 預設 |
|---|---|---|
uid |
用於所有檔案擁有者的使用者識別碼 | WSL 發行版本版本的預設使用者識別碼 (在第一次安裝時，此預設值為1000) |
gid |
用於所有檔案擁有者的群組識別碼 | WSL 發行版本版本的預設群組識別碼 (在第一次安裝時，此預設值為1000) |
umask |
要排除所有檔案和目錄的權限八進位遮罩 | 022 |
fmask |
要排除所有檔案的權限八進位遮罩 | 000 |
dmask |
要排除所有目錄的權限八進位遮罩 | 000 |
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 (目錄)。
注意
許可權遮罩會在套用至檔案或目錄之前，先執行邏輯 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 |
字串 | Windows 主機名稱 | 設定要用於 WSL 發行版本的主機名稱。 |
互通性設定
wsl.conf 區段卷標： [interop]
這些選項可在測試人員組建 17713 和更新版本中使用。
| 索引鍵 | value | 預設值 | 附註 |
|---|---|---|---|
enabled |
boolean | true |
設定此機碼將決定 WSL 是否支援啟動 Windows 程序。 |
appendWindowsPath |
boolean | true |
設定此機碼將決定 WSL 是否會將 Windows 路徑元素新增至 $PATH 環境變數。 |
使用者設定
wsl.conf 區段卷標： [user]
這些選項可在組建 18980 和更新版本中取得。
| 索引鍵 | value | 預設值 | 附註 |
|---|---|---|---|
default |
字串 | 第一次執行時建立的初始使用者名稱 | 設定此金鑰會指定第一次啟動 WSL 工作階段時要執行的使用者。 |
開機設定
開機設定僅適用於 Windows 11 和 Server 2022。
wsl.conf 區段卷標： [boot]
| 索引鍵 | value | 預設值 | 附註 |
|---|---|---|---|
command |
字串 | "" | 您想要在 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 路徑。 |
memory |
size | Windows 上總記憶體的 50% | 要指派給 WSL 2 VM 的記憶體量。 |
processors |
數值 | Windows 上相同的邏輯處理器數目 | 要指派給 WSL 2 VM 的邏輯處理器數目。 |
localhostForwarding |
boolean | true |
布林值，指定 WSL 2 VM 中繫結至萬用字元或 localhost 的連接埠是否應該可透過 localhost:port 從主機連線。 |
kernelCommandLine |
字串 | 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) 支援的布林值。 |
debugConsole* |
boolean | false |
可開啟輸出主控台視窗的布林值，顯示 WSL 2 發行版本執行個體啟動時 dmesg 的內容。 僅適用於 Windows 11。 |
nestedVirtualization* |
boolean | true |
可開啟或關閉巢狀虛擬化的布林值，讓其他巢狀 VM 能夠在 WSL 2 內執行。 僅適用於 Windows 11。 |
vmIdleTimeout* |
數值 | 60000 |
VM 在關閉之前閒置的毫秒數。 僅適用於 Windows 11。 |
dnsProxy |
boolean | true |
僅適用於 networkingMode = NAT。 布爾值，通知 WSL 將 Linux 中的 DNS 伺服器設定為主機上的 NAT。 將 設定為 false 會將 DNS 伺服器從 Windows 鏡像到 Linux。 |
networkingMode** |
字串 | NAT |
如果值為 mirrored，則這會開啟鏡像網路模式。 預設或無法辨識的字串會導致 NAT 網路。 |
firewall** |
boolean | true |
將此設定為 true 可讓 Windows 防火牆規則，以及 Hyper-V 流量專屬的規則來篩選 WSL 網路流量。 |
dnsTunneling** |
boolean | true |
變更將 DNS 要求從 WSL 代理至 Windows 的方式 |
autoProxy* |
boolean | true |
強制 WSL 使用 Windows 的 HTTP Proxy 資訊 |
defaultVhdSize |
size | 1099511627776 （1TB） |
設定儲存 Linux 發行版 （例如 Ubuntu） 檔案系統的虛擬硬碟 （VHD） 大小。 可用來限制允許散發檔系統佔用的大小上限。 |
具有 path 值的項目必須是具有逸出反斜線的 Windows 路徑，例如：C:\\Temp\\myCustomKernel
具有 size 值的項目必須是大小，後面接著單位，例如 8GB 或 512MB。
在值類型之後具有 * 的項目只能在 Windows 11 上使用。
在實值類型之後具有 ** 的專案需要 Windows 11 版本 22H2 或更高版本。
實驗性設定
這些設定是實驗性功能的選擇預覽，我們的目標是在未來設為預設值。
.wslconfig 區段卷標： [experimental]
| 設定名稱 | 值 | 預設 | 備註 |
|---|---|---|---|
autoMemoryReclaim |
字串 | disabled |
偵測閒置 CPU 使用量之後，自動釋放快取的記憶體。 設定為 gradual 以緩慢釋放，而設定為 dropcache 會立即釋放快取的記憶體。 |
sparseVhd |
bool | false |
當設定為 true 時，任何新建立的 VHD 都會自動設定為疏鬆。 |
bestEffortDnsParsing** |
bool | false |
只有在 wsl2.dnsTunneling 設定為 true 時才適用。 當設定為 true 時，Windows 會從 DNS 要求擷取問題，並嘗試加以解決，同時忽略未知的記錄。 |
dnsTunnelingIpAddress** |
字串 | 10.255.255.254 |
只有在 wsl2.dnsTunneling 設定為 true 時才適用。 指定啟用 DNS 信道時，將在 Linux resolv.conf 檔案中設定的名稱伺服器。 |
initialAutoProxyTimeout* |
字串 | 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位址。 |
在值類型之後具有 * 的項目只能在 Windows 11 上使用。
在實值類型之後具有 ** 的專案需要 Windows 22H2 版或更高版本。
範例 .wslconfig 檔案
下列 .wslconfig 範例檔案示範一些可用的設定選項。 在此範例中，檔案路徑為 C:\Users\<UserName>\.wslconfig。
# Settings apply across all Linux distros running on WSL 2
[wsl2]
# Limits VM memory to use no more than 4 GB, this can be set as whole numbers using GB or MB
memory=4GB
# Sets the VM to use two virtual processors
processors=2
# Specify a custom Linux kernel to use with your installed distros. The default kernel used can be found at https://github.com/microsoft/WSL2-Linux-Kernel
kernel=C:\\temp\\myCustomKernel
# Sets additional kernel parameters, in this case enabling older Linux base images such as Centos 6
kernelCommandLine = vsyscall=emulate
# Sets amount of swap storage space to 8GB, default is 25% of available RAM
swap=8GB
# Sets swapfile path location, default is %USERPROFILE%\AppData\Local\Temp\swap.vhdx
swapfile=C:\\temp\\wsl-swap.vhdx
# Disable page reporting so WSL retains all allocated memory claimed from Windows and releases none back when free
pageReporting=false
# Turn on default connection to bind WSL 2 localhost to Windows localhost. Setting is ignored when networkingMode=mirrored
localhostforwarding=true
# Disables nested virtualization
nestedVirtualization=false
# Turns on output console showing contents of dmesg when opening a WSL 2 distro for debugging
debugConsole=true
# Enable experimental features
[experimental]
sparseVhd=true
