wsl.conf 和 .wslconfig 檔案可用來在 WSL 中設定進階設定，以在 WSL VM 啟動時套用。
wsl.conf 用於根據每個 WSL 發行版本套用設置，而 .wslconfig 則用於將全域設置套用至 WSL。 您可以進一步瞭解以下的差異。
| 方面 | .wslconfig |
wsl.conf |
|---|---|---|
| Scope | 適用於所有 WSL 的一般設定 | 僅適用於 WSL 版本的設定 |
| 配置 | WSL 中的功能啟用、為 WSL 2 提供電源的虛擬機設定（RAM、要開機的核心、CPU 數目等等） | WSL 中的發行版設定，例如開機選項、DrvFs 自動掛接、網路功能、與 Windows 系統的互操作性、systemd 使用和預設使用者 |
| 位置 |
%UserProfile%\.wslconfig在 WSL 系統之外 |
/etc/wsl.conf，而在 WSL 發行版內 |
目前，所有 .wslconfig 設定僅適用於 WSL 2 發行版。 瞭解 如何檢查您執行的 WSL 版本。
組態變更的 8 秒規則
您必須等到執行 Linux 發行版本的子系統完全停止執行並重新啟動，才能顯示組態設定更新。 關閉發行版本殼層的「所有」執行個體之後，這通常需要大約 8 秒的時間。
如果您啟動發行版本 (例如 Ubuntu)，請修改組態檔、關閉發行版本，然後重新啟動，您可能會假設您的設定變更已立即生效。 目前情況並非如此，因為子系統仍然可以執行。 您必須等候子系統停止後再重新啟動，以便有足夠的時間讓您的變更生效。 您可以使用 PowerShell 搭配命令 wsl --list --running，在關閉之後檢查 Linux 發行版本 (Shell) 是否仍在執行中。 如果沒有發行版本正在執行，您會收到回應：「沒有執行中的發行版本。」您現在可以重新啟動發行版本，以查看套用的設定更新。
命令 wsl --shutdown 是快速關閉 WSL 2 發行版本的方法，但會關閉所有正在執行的發行版本，因此請妥善使用。 您也可以使用 wsl --terminate <distroName> 來立即終止特定正在執行的散發版本。
wsl.conf
使用 wsl.conf 為每個在 WSL 1 或 WSL 2 上運行的 Linux 發行版配置區域設置。
- 儲存在發行版本的
/etc目錄中，作為一個 unix 檔案。 - 用來進行個別發行版本的設定。 此檔案中進行的設定只會套用至包含儲存此檔案所在目錄的特定 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，請使用 wsl.conf 以取得系統管理員權限，在文字編輯器中開啟您的 sudo 檔案，並將這幾行新增至 /etc/wsl.conf：
[boot]
systemd=true
接著，您必須使用 wsl.exe --shutdown 從 PowerShell 關閉 WSL 發行版本，以重新啟動您的 WSL 執行個體。 當您的發行版本重新啟動後，systemd 應該會開始運行。 您可以使用命令 systemctl list-unit-files --type=service 進行確認，這會顯示服務的狀態。
自動掛接設定
wsl.conf 區段卷標： [automount]
| 關鍵 | 價值 | 預設 | 備註 |
|---|---|---|---|
enabled |
布爾值 | true |
true 導致固定磁碟機（例如 C:/ 或 D:/）會自動使用 DrvFs 掛載在 /mnt。
false 表示磁碟機不會自動掛載，但您仍然可以手動掛載或通過 fstab 進行挂载。 |
mountFsTab |
布爾值 | 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、fmask 等選項只有在 Windows 磁碟驅動器掛接元數據時才適用。 預設不會啟用元數據。 您可以 在這裡找到詳細資訊。
注意
許可權遮罩會在套用至檔案或目錄之前，先執行邏輯 OR 作業。
什麼是 DrvFs？
DrvFs 是 WSL 的檔案系統外掛程式，其設計目的是支援 WSL 與 Windows 檔案系統之間的互通性。 DrvFs 可讓 WSL 在 /mnt 下以支援的檔案系統掛接磁碟機，例如 /mnt/c、/mnt/d 等。如需掛接 Windows 或 Linux 磁碟機或目錄時指定預設區分大小寫行為的詳細資訊，請參閱區分大小寫頁面。
網路設定
wsl.conf 區段卷標： [network]
| 關鍵 | 價值 | 預設 | 備註 |
|---|---|---|---|
generateHosts |
布爾值 | true |
true 將 WSL 設定為產生 /etc/hosts。
hosts 檔案包含一張主機名稱對應 IP 位址的靜態地圖。 |
generateResolvConf |
布爾值 | true |
true 將 WSL 設定為產生 /etc/resolv.conf。
resolv.conf 包含可以將指定主機名稱解析成其 IP 位址的 DNS 清單。 |
hostname |
字串 | Windows 主機名稱 | 設定要用於 WSL 發行版本的主機名稱。 |
互通性設定
wsl.conf 區段卷標： [interop]
這些選項可在內部預覽版本 17713 及更高版本中使用。
| 關鍵 | 價值 | 預設 | 備註 |
|---|---|---|---|
enabled |
布爾值 | true |
設定此機碼將決定 WSL 是否支援啟動 Windows 程序。 |
appendWindowsPath |
布爾值 | true |
設定此索引鍵會判斷 WSL 是否會將 Windows 路徑專案新增至 $PATH 環境變數。 |
使用者設定
wsl.conf 區段卷標： [user]
這些選項可在版本 18980 和更新的版本中取得。
| 關鍵 | 價值 | 預設 | 備註 |
|---|---|---|---|
default |
字串 | 第一次執行時建立的初始使用者名稱 | 設定此設定會指定首次啟動 WSL 時要執行的使用者。 |
開機設定
開機設定僅適用於 Windows 11 和 Server 2022。
wsl.conf 區段卷標： [boot]
| 關鍵 | 價值 | 預設 | 備註 |
|---|---|---|---|
command |
字串 | 零 | 您想要在 WSL 執行個體啟動時執行的命令字串。 此命令會以根使用者身分執行。 例如：service docker start。 |
protectBinfmt |
布爾值 | true |
防止 WSL 在啟用 systemd 時產生 systemd 單元。 |
GPU 設定
wsl.conf 區段卷標： [gpu]
| 關鍵 | 價值 | 預設 | 備註 |
|---|---|---|---|
enabled |
布爾值 | true |
允許Linux應用程式透過para-virtualization存取 Windows GPU。 |
時間設定
wsl.conf 區段卷標： [time]
| 關鍵 | 價值 | 預設 | 備註 |
|---|---|---|---|
useWindowsTimezone |
布爾值 | true |
設定此金鑰會讓 WSL 使用並同步至 Windows 中設定的時區。 |
範例 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 執行的發行版本不會受到此設定的影響，因為其不是以虛擬機器執行。
- 若要進入您的 目錄，請在 PowerShell 中使用 來存取主目錄 (通常是您的使用者資料夾, )，或者您可以開啟 Windows 檔案總管並在位址列中輸入 。 目錄路徑看起來應該類似於：
/etc/wsl.conf。
WSL 會偵測這些檔案是否存在、讀取內容，並在每次啟動 WSL 時自動套用組態設定。 如果檔案遺失或格式不正確 (標記格式不正確)，WSL 會繼續正常啟動，而不會套用組態設定。
.wslconfig 的組態設定
.wslconfig 檔案會針對使用 WSL 2 執行的所有 Linux 發行版本全域進行設定。 (如需個別發行版本設定，請參閱 wsl.conf)。
如需 .wslconfig 檔案儲存位置的資訊，請參閱 .wslconfig。
注意
使用 .wslconfig 設定全域設定僅適用於在 Windows 組建 19041 和更新版本中以 WSL 2 身分執行的散發套件。 請記住，您可能需要執行 wsl --shutdown 來關閉 WSL 2 VM，然後重新啟動您的 WSL 實例，使這些變更生效。
小提示
建議您直接在 WSL 設定中修改 WSL 組態，而不是手動編輯 .wslconfig 檔案。 您可以在 [開始] 選單中找到 WSL 設定。
此檔案可以包含下列選項，這些選項會影響支援任何 WSL 2 發行版本的 VM：
主要 WSL 設定
.wslconfig 區段卷標： [wsl2]
| 關鍵 | 價值 | 預設 | 備註 |
|---|---|---|---|
kernel |
路徑 | Microsoft 建置核心提供的收件匣 | 自訂 Linux 核心的絕對 Windows 路徑。 |
kernelModules |
路徑 | 自訂Linux核心模組 VHD 的絕對 Windows 路徑。 | |
memory |
尺寸 | Windows 上總記憶體的 50% | 要指派給 WSL 2 VM 的記憶體量。 |
processors |
數字 | 相同的邏輯處理器數目在 Windows 上 | 要指派給 WSL 2 VM 的邏輯處理器數目。 |
localhostForwarding |
布爾值 | true |
布林值，指定在 WSL 2 VM 中繫結到萬用字元或 localhost 的連接埠是否應該可透過 localhost:port從主機進行連接。 |
kernelCommandLine |
字串 | 沒有 | 其他核心命令列引數。 |
safeMode |
布爾值 | false |
在「安全模式」中執行 WSL 會停用許多功能，而目的是用來復原處於不良狀態的發行版本。 僅適用於 Windows 11 和 WSL 0.66.2+版。 |
swap |
尺寸 | Windows 上 25% 的記憶體大小四捨五入至最接近的 GB | 請設定要新增至 WSL 2 VM 的交換空間大小，若不需要交換檔案，請設為 0。 交換儲存體是以磁碟為基礎的 RAM，在記憶體需求超過硬體裝置的限制時使用。 |
swapFile |
路徑 | %Temp%\swap.vhdx |
交換虛擬硬碟的絕對 Windows 路徑。 |
pageReporting |
布爾值 | true |
設定可讓 Windows 回收配置給 WSL 2 虛擬機的未使用記憶體。 |
guiApplications |
布爾值 | true |
布林值，用於在 WSL 中開啟或關閉對 GUI 應用程式 (WSLg) 的支援。 |
debugConsole1 |
布爾值 | false |
可用布林值來開啟輸出控制台視窗，以便在 WSL 2 發行版執行個體啟動時顯示 dmesg 的內容。 |
maxCrashDumpCount |
數字 | 10 |
設定為了偵錯而保留的損毀傾印檔案數目上限。 WSL 保留的預設數位為 10。 超過此限制時，系統會自動刪除較舊的損毀傾印，以騰出空間供新的傾印使用。 設定 max 有助於減少這些損毀檔案所使用的磁碟空間量。 |
nestedVirtualization1 |
布爾值 | true |
可開啟或關閉巢狀虛擬化的布林參數，讓其他巢狀 VM 能夠在 WSL 2 中執行。 |
vmIdleTimeout1 |
數字 | 60000 |
VM 在關閉之前閒置的毫秒數。 |
dnsProxy |
布爾值 | true |
只適用於 networkingMode = NAT。 布爾值，通知 WSL 將 Linux 中的 DNS 伺服器設定為主機上的 NAT。 將 設定為 false 會將 DNS 伺服器從 Windows 鏡像到 Linux。 |
networkingMode¹² |
字串 | NAT |
可用的值為：none、、 netbridged 、（已淘汰）、mirrored和 virtioproxy。 如果值為 none，則會中斷 WSL 網路連線。 如果值為 net 或未知的值，則會使用 NAT 網路模式（從 WSL 2.3.25 開始，如果 NAT 網路模式失敗，則會回復為使用 VirtioProxy 網路模式）。 如果值為 bridged，則會使用橋接網路模式（此模式自 WSL 2.4.5 起已標示為已被取代）。 如果值為 mirrored，則會使用鏡像網路模式。 如果值為 virtioproxy，則會使用 VirtioProxy 網路模式。 |
firewall¹² |
布爾值 | true |
將此設定為 true 可讓 Windows 防火牆規則，以及 Hyper-V 流量專屬的規則來篩選 WSL 網路流量。 |
dnsTunneling¹² |
布爾值 | true |
變更將 DNS 要求從 WSL 代理至 Windows 的方式 |
autoProxy1 |
布爾值 | true |
強制 WSL 使用 Windows 的 HTTP Proxy 資訊 |
defaultVhdSize |
尺寸 |
1099511627776 （1 TB） |
設定儲存 Linux 發行版 （例如 Ubuntu） 檔案系統的虛擬硬碟 （VHD） 大小。 可用來限制允許散發檔系統佔用的大小上限。 |
具有 「path」 值的項目必須是具有逸出反斜杠的 Windows 路徑，例如： C:\\Temp\\myCustomKernel
size值為 B（位元組）且單位為允許的專案。 若要使用其他單位，必須附加大小單位，例如： 8GB 或 512MB。
2：僅適用於 Windows 11。
2：需要 Windows 11 版本 22H2 或更高版本。
實驗性設定
這些設定是實驗性功能的選擇預覽，我們的目標是在未來設為預設值。
.wslconfig 區段卷標： [experimental]
| 關鍵 | 價值 | 預設 | 備註 |
|---|---|---|---|
autoMemoryReclaim |
字串 | dropCache |
可用的值為： disabled、 gradual與 dropCache。 如果值為 disabled，則會停用WSL自動記憶體回收。 如果值為 gradual，快取的記憶體將會以緩慢且自動方式回收。 如果值為 dropCache 或未知的值，則會立即回收快取的記憶體。 |
sparseVhd |
布林 | false |
當設定為 true時，任何新建立的 VHD 都會自動設定為疏鬆。 |
bestEffortDnsParsing¹² |
布林 | false |
只有當 wsl2.dnsTunneling 設定為 true 時才適用。 當設定為 true時，Windows 會從 DNS 要求擷取問題，並嘗試加以解決，忽略未知的記錄。 |
dnsTunnelingIpAddress¹² |
字串 | 10.255.255.254 |
只有當 wsl2.dnsTunneling 設定為 true 時才適用。 指定啟用 DNS 通道時，將在 Linux resolv.conf 檔案中設定的名稱伺服器。 |
initialAutoProxyTimeout1 |
字串 | 1000 |
只有當 wsl2.autoProxy 設定為 true 時才適用。 設定 WSL 容器啟動時，WSL 等候擷取 HTTP proxy 資訊的時間長度（以毫秒為單位）。 如果代理設定在此時間之後解析完畢，則必須重新啟動 WSL 執行個體，才能使用取得的代理設定。 |
ignoredPorts¹² |
字串 | 零 | 只有當 wsl2.networkingMode 設定為 mirrored 時才適用。 指定 Linux 應用程式可以繫結至哪些連接埠，即使該連接埠用於 Windows 也一樣。 這可讓應用程式僅在 Linux 上監聽流量端口，因此即使該端口在 Windows 上用於其他用途，這些應用程式仍不會被阻擋。 例如，WSL 將允許系結至適用於 Docker Desktop 的 Linux 連接埠 53，因為它只會接聽 Linux 容器內的要求。 應該以逗號分隔清單格式化，例如： |
hostAddressLoopback¹² |
布林 | false |
只有當 wsl2.networkingMode 設定為 mirrored 時才適用。 當設定為 true 時，將允許容器使用分配給主機的IP位址連接至主機，或主機連接至容器。
127.0.0.1 回送位址可以始終使用，此選項允許使用所有額外指派的本機 IP 位址。 僅支援指派給主機的IPv4位址。 |
2：僅適用於 Windows 11。
2：需要 Windows 11 版本 22H2 或更高版本。
範例 .wslconfig 檔案
下面的 .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
# Specify the modules VHD for the custum Linux kernel to use with your installed distros.
kernelModules=C:\\temp\\modules.vhdx
# 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
# Sets the maximum number of crash dump files to retain (default is 5)
maxCrashDumpCount=10
# Enable experimental features
[experimental]
sparseVhd=true
