建立 WSL 的自定義 Linux 發行版

本指南將逐步解說建立和發佈 WSL 發行版的步驟，也就是一種 .wsl 檔案。

WSL 發行版有兩個部分：

根檔案系統（以 tar 檔案的形式散發）
清單項目（其中包含發行元資料）

本指南僅適用於 WSL 2.4.4 版和更新版本。

注意

如需先前以appx為基礎的發行打包說明，請參閱此存放庫。

什麼是 WSL 根文件系統 tar 檔案？

WSL 發行版本是由 Windows 上具有 .wsl 副檔名的 tar 檔案所定義。

TAR 檔案（磁帶封存簡短）是一種封存盤案，用來將多個檔案儲存在單一檔案中，以方便散發或備份。 TAR 檔案包含 Linux 發行版的根文件系統（所有散發檔案），以及 WSL 組態檔。 WSL 組態檔會告知 WIndows 作業系統如何安裝和啟動散發套件。

一旦您有想要進入 WSL 發行版的 Linux 系統，請遵循下列步驟來開始使用。

建立 WSL 組態檔

發行版必須包含兩個組態檔：

/etc/wsl-distribution.conf：由發行版維護者建立的檔案，負責在第一次使用 WSL 啟動時配置 Linux 發行版的方式。
/etc/wsl.conf：包含用戶專屬的全域系統設定，並控制發佈啟動方式的檔案。深入瞭解 WSL 組態檔。。

新增 WSL 發行版設定檔案

首次啟動時，發行版配置檔 /etc/wsl-distribution.conf 定義了 Linux 發行版應如何配置。此檔案可用來以互動方式建立用戶帳戶、顯示許可協定等。

以下是範例 /etc/wsl-distribution.conf 檔案：

# /etc/wsl-distribution.conf

[oobe]
command = /etc/oobe.sh
defaultUid = 1000
defaultName = my-distro

[shortcut]
enabled = true
icon = /usr/lib/wsl/my-icon.ico

[windowsterminal]
enabled = true
ProfileTemplate = /usr/lib/wsl/terminal-profile.json

WSL 發行版本組態選項：

鑰匙	價值觀	預設	註釋
`oobe.command`	字串	沒有	OOBE 代表開箱體驗。此命令會在使用者第一次開啟發行版中的互動式殼層時執行。如果該命令傳回非零值，則會將其視為失敗，而且使用者將無法開啟命令提示符。
`oobe.defaultUid`	整數	沒有	發行版啟動時的預設UID。當 `oobe.command` 腳本建立新使用者時，這非常有用。
`oobe.defaultName`	字串	沒有	發行版之下註冊的預設名稱。這個預設名稱可以取代為命令： `wsl.exe --install <distro> --name <name>`
`shortcut.icon`	字串	默認 WSL 圖示	發行版在開始功能表中的快捷方式圖示。必須採用 `.ico` 格式，且大小不得超過 `10MB`。
`shortcut.enabled`	布林值	真實	安裝發行套件時，是否應該建立開始功能表捷徑。
`windowsterminal.profileTemplate`	字串	沒有	用於此發行版的 Windows 終端機設定檔生成的 JSON 範本。
`windowsterminal.enabled`	布林值	真實	安裝發行版時，是否應該建立終端機配置檔。如果未設定 `profileTemplate`，則會產生預設配置檔。
`windowsterminal.profileTemplate`	字串	終端機範本檔案的路徑	用於此發行版的 Windows 終端機設定檔生成的 JSON 範本。

您需要為發行版建立開箱體驗和初次執行體驗。以下是您可以使用的範例 Bash 腳本。這個文稿假設設定 oobe.defaultUid 為 1000：

#!/bin/bash

set -ue

DEFAULT_GROUPS='adm,cdrom,sudo,dip,plugdev'
DEFAULT_UID='1000'

echo 'Please create a default UNIX user account. The username does not need to match your Windows username.'
echo 'For more information visit: https://aka.ms/wslusers'

if getent passwd "$DEFAULT_UID" > /dev/null ; then
  echo 'User account already exists, skipping creation'
  exit 0
fi

while true; do

  # Prompt from the username
  read -p 'Enter new UNIX username: ' username

  # Create the user
  if /usr/sbin/adduser --uid "$DEFAULT_UID" --quiet --gecos ''  "$username"; then

    if /usr/sbin/usermod "$username" -aG "$DEFAULT_GROUPS"; then
      break
    else
      /usr/sbin/deluser "$username"
    fi
  fi
done

產生 Windows 終端機配置檔

當安裝發行版時，WSL 會自動建立 Windows 終端機設定檔。散發維護人員可以在 WSL 組態檔 windowsterminal.profileTemplate 中設定/etc/wsl-distribution.conf，以自定義生成的設定檔。

json 檔案會遵循終端機配置檔 json 格式。以下是一個範例個人檔案：

{
  "profiles": [
    {
      "antialiasingMode": "aliased",
      "fontWeight": "bold",
      "colorScheme": "Postmodern Tango Light"
    }
  ],
  "schemes": [
    {
      "name": "Postmodern Tango Light",
      "black": "#0C0C0C",
      "red": "#C50F1F",
      "green": "#13A10E",
      "yellow": "#C19C00",
      "blue": "#0037DA",
      "purple": "#881798",
      "cyan": "#3A96DD",
      "white": "#CCCCCC",
      "brightBlack": "#767676",
      "brightRed": "#E74856",
      "brightGreen": "#16C60C",
      "brightYellow": "#F9F1A5",
      "brightBlue": "#3B78FF",
      "brightPurple": "#B4009E",
      "brightCyan": "#61D6D6",
      "brightWhite": "#F2F2F2"
    }
  ]
}

此檔案不需要指定設定檔 name或 commandLine。產生終端機配置檔時，WSL 會自動新增這些配置檔。

針對每個發行版本機設定新增 WSL 配置

在分發根文件系統的上下文中，我們建議您在每個分發的本機設定中配置 systemd 的設定，包括 systemd 是否預設啟動。請參閱以下範例。

# /etc/wsl.conf

[boot]
systemd=true|false

發行版作者藉由設定 boot.systemd 的值為 true （啟用）或 false （未啟用）來決定 systemd 是否默認啟用。

如果您選擇預設啟用 systemd，請參閱 Systemd 建議。

如需中所有支持的設定，請參閱/etc/wsl.conf中的進階設定組態。

建立 tar 檔案

一旦發佈和組態檔就緒，就可以在 tar 檔案中擷取根文件系統。

建立 tar 檔案的建議方式：

cd /path/to/rootfs
tar --numeric-owner --absolute-names -c  * | gzip --best > ../install.tar.gz

tar 的根目錄應該是檔案系統的根目錄（不是包含根文件系統的目錄）。

建議的壓縮格式為 gzip。其他壓縮格式可能會造成與舊的 WSL 版本破壞相容性的風險。

如需應該和不應該包含在組態中的檔案清單，請參閱組態檔建議。

若要取得現有 Linux 發行版的 tar 檔案，請尋找如何在導出 Docker 容器，以匯入至任何要與 WSL搭配使用的 Linux 發行版的指引。

一旦 tar 檔案封存就緒，請參閱在本機測試發行版，以測試它。

建立 .wsl 副檔名

一旦您建立 tar 檔案來代表自定義 Linux 發行版，最後一個步驟就是藉由重新命名，將 .tar 擴展名變更為 .wsl 擴展名。重新命名此副檔名會將它標示為WSL發行版。將 tar 從 .tar 重新命名為 .wsl之後，檔案會在檔案總管中開啟時正確安裝在 Windows 上（按兩下）。 oobe.defaultName 檔案中需要 /etc/wsl-distribution.conf 項目，才能讓這個雙擊操作正常運作。

發行您的 WSL 發行版

WSL 使用者可以執行 wsl --list --online 來檢視可用的發行版，並可直接使用 wsl --install <distroName> 安裝它們（以 Linux 發行版的實際名稱取代 <distroName>。此過程由分發清單文件控制。您可以將此指令清單檔案新增至客戶 Linux 發行版，使其包含在命令選項中 wsl --install 。

您已建立並重新命名為 .wsl 擴展名的自訂 Linux 發行版本 tar，可以隨意分發。使用者下載後，可以直接從命令列安裝 wsl --install --from-file <fileLocation>（將 <fileLocation> 替換為檔案的實際位置）。或者，您可以按兩下開啟自訂 WSL 發行版的.wsl檔案。

分發清單詳細資料

安裝清單包含透過安裝的發行版相關中繼資料。

基於 tar 的 Linux 發行版本會列在 ModernDistribution下，格式如下：

{
    "ModernDistributions": {
        "<flavor>": [
            {
                "Name": "<version name>",
                "FriendlyName": "<friendly name>",
                "Default": true | false,
                "Amd64Url": {
                    "Url": "<tar url>",
                    "Sha256": "<tar sha256 hash>"
                },
                "Arm64Url": {
                    "Url": "<tar url>",
                    "Sha256": "<tar sha256 hash>"
                }
            },
            {
                ...
            }
        ],
        "<flavor>": [
            ...
        ]
    }
}

每個 flavor 條目都包含可安裝的發行版清單。發行版可以通過風味名稱（這種情況下將安裝預設項目）或版本名稱來安裝。

看看 wsl --install 指令如何與下面的清單一起運作：

{
    "ModernDistributions": {
        "my-distro": [
            {
                "Name": "my-distro-v3",
                "Default": true,
                "FriendlyName": "My distribution version 3 (latest)"
                [...]
            },
            {
                "Name": "my-distro-v2",
                "Default": false,
                "FriendlyName": "My distribution version 2"
                [...]
            }
        ]
    }
}

範例安裝命令：

wsl --install my-distro # Installs 'my-distro-v3' since it's the default for 'my-distro' flavor
wsl --install my-distro-v3 # Installs 'my-distro-v3' explicitly
wsl --install my-distro-v2 # Installs 'my-distro-v2' explicitly

將您的發行版新增至所有 WSL 使用者的 `wsl --install`

若要讓您的發行套件包含在命令 wsl --list --online的清單中：，該發行套件必須符合發行套件郵件清單中概述的成員資格條件。這確保了所有列出的發行版都遵守必要的安全標準。

如果您的散佈軟體符合準則，並且您希望將其新增至 --install 清單，請在 WSL 的 GitHub 儲存庫（https://github.com/microsoft/WSL）中提交一個拉取請求，以更新 DistributionInfo.json 檔案，加入您的散佈軟體詳細訊息。 WSL 小組將會檢閱此提取要求。

將您的分配添加至企業或商務群組的 `wsl --install`

您也可以藉由編輯選擇的 Windows 裝置上的註冊表機碼，讓發行版僅在 wsl --install 中提供給特定群組。

在中 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss建立登錄值，即可覆寫 WSL 散發指令清單。

DistributionListUrl：覆寫散發指令清單 URL
DistributionListUrlAppend：將該資訊清單 URL 的發行套件新增至可安裝的發行套件清單中

這兩個登錄值都是字串（REG_SZ），而且必須是URL格式。

從 WSL 2.4.4 版開始，支援 file:// 通訊協定，讓本機測試更容易。預期格式為：file:///C:/path/to/file。

在本機測試分佈

若要測試散發的 tar 檔案，您可以使用下列範例 PowerShell 腳本，以新的散發覆寫散發清單。首先將下列文稿儲存為 override-manifest.ps1：

#Requires -RunAsAdministrator

[cmdletbinding(PositionalBinding = $false)]
param (
    [Parameter(Mandatory = $true)][string]$TarPath,
    [string]$Flavor = "test-distro",
    [string]$Version = "test-distro-v1",
    [string]$FriendlyName = "Test distribution version 1")

Set-StrictMode -Version latest

$TarPath = Resolve-Path $TarPath
$hash = (Get-Filehash $TarPath -Algorithm SHA256).Hash


$manifest= @{
    ModernDistributions=@{
        "$Flavor" = @(
            @{
                "Name" = "$Version"
                Default = $true
                FriendlyName = "$FriendlyName"
                Amd64Url = @{
                    Url = "file://$TarPath"
                    Sha256 = "0x$hash"
                }
            })
        }
    }

$manifestFile = "$PSScriptRoot/manifest.json"
$manifest | ConvertTo-Json -Depth 5 | Out-File -encoding ascii $manifestFile


Set-ItemProperty -Path "HKLM:SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss" -Name DistributionListUrl -Value "file://$manifestFile" -Type String -Force

然後在提升權限的 Powershell 中執行下列命令，以設定本機指令清單：

.\override-manifest.ps1 -TarPath /path/to/tar

完成後，您應該會看到下列來自 wsl.exe --list --online的輸出：

$ wsl --list --online
The following is a list of valid distributions that can be installed.
Install using 'wsl.exe --install <Distro>'.

NAME              FRIENDLY NAME
test-distro-v1    Test distribution version 1

然後，您可以執行 wsl.exe --install test-distro-v1 來嘗試安裝新的發行版。

完成時，您可以刪除 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\DistributionListUrl 以還原為官方指令清單。

WSL 自訂 Linux 發行版建議

設定檔建議

請確定您的自定義發行版同時包含 /etc/wsl.conf 和 /etc/wsl-distribution.conf 組態檔。這兩個檔案都應該由 root:root 擁有，而且其許可權應該 0644。
如果使用 oobe.command 設定來建立新的使用者，uid 和 oobe.defaultUid 都應該設定為 1000。
請確定您在分佈設定檔中同時設定 oobe.defaultName 和 shortcut.icon：/etc/wsl-distribution.conf
請勿在根文件系統中包含檔案 /etc/resolv.conf。
請在 /etc/passwd中包含根使用者。此根使用者的 uid 應為 0。
/etc/shadow中不應該有密碼哈希。
封存不應包含核心或 initramfs。

Systemd 建議

如果已啟用 systemd，應該停用或遮罩可能導致 WSL 問題的單位。已知下列單元會在 WSL 發行版中引起問題（適用於系統單元和用戶單元）：

systemd-resolved.service
systemd-networkd.service
NetworkManager.service
systemd-tmpfiles-setup.service
systemd-tmpfiles-clean.service
systemd-tmpfiles-clean.timer
systemd-tmpfiles-setup-dev-early.service
systemd-tmpfiles-setup-dev.service
tmp.mount

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-09-12