Ian Chou's Blog

WSL 2 圖形界面完整指南：Wayland、WSLg 與 Windows 互通

WSL 2 圖形界面完整指南：Wayland、WSLg 與 Windows 互通

本文記錄在 WSL 2 環境中使用圖形界面應用程式的完整架構，包括 Wayland 支援、WSL Interop 機制，以及 IDE (如 Antigravity/VS Code) 的 Remote Development 連接原理。

目錄

環境概述

測試環境：

WSLg 與 Wayland

什麼是 WSLg？

WSLg (Windows Subsystem for Linux GUI) 是微軟提供的解決方案，讓 Linux GUI 應用程式可以在 Windows 桌面環境中無縫執行。

架構圖

Windows 11 桌面
└── WSLg System Distro
    ├── Weston (Wayland Compositor)
    ├── XWayland (X11 相容層)
    ├── PulseAudio (音訊)
    └── RDP Server → Windows 顯示
        ↓
└── WSL Ubuntu
    └── Linux GUI 應用程式 (GTK, Qt 等)
        └── Wayland socket: /mnt/wslg/runtime-dir/

關鍵特點

特點 說明
Wayland 原生支援 現代 Linux 應用程式直接使用 Wayland 協議
X11 向下相容 透過 XWayland 支援舊版 X11 應用程式
GPU 加速 透過 DirectX 整合實現硬體加速
音訊支援 透過 PulseAudio 提供音訊功能

驗證 Wayland 支援

1. 檢查 WSLg 是否正常運作

# 檢查 WSLg 目錄
ls -la /mnt/wslg/

# 預期輸出應包含：
# - weston.log
# - runtime-dir/
# - PulseServer

2. 檢查環境變數

echo "WAYLAND_DISPLAY: $WAYLAND_DISPLAY"
echo "DISPLAY: $DISPLAY"

# 預期輸出：
# WAYLAND_DISPLAY: wayland-0
# DISPLAY: :0

3. 檢查 Wayland Socket

ls -la /mnt/wslg/runtime-dir/

# 應該看到：
# wayland-0
# wayland-0.lock

4. 使用 wayland-info 工具驗證

# 安裝工具
sudo apt install -y wayland-utils

# 執行驗證
wayland-info | head -30

# 成功輸出應包含：
# interface: 'wl_compositor', version: 4
# interface: 'xdg_wm_base', version: 1

5. 檢查 WSLg 版本

cat /mnt/wslg/versions.txt

# 輸出範例：
# WSLg ( x86_64 ): 1.0.71
# Mariner: VERSION="2.0.20250701"
# weston: 2318fecaeac1f1a2d5a7a042c34d931c71dae04c

WSL Interop：執行 Windows 應用程式

什麼是 WSL Interop？

WSL Interop 允許你在 WSL 終端機中直接執行 Windows .exe 應用程式，就像在 Windows 命令提示字元中一樣。

架構圖

┌─────────────────────────────────────────────────────────────┐
│  WSL Terminal                                                │
│  $ notepad.exe file.txt                                      │
│       ↓                                                      │
│  WSL 偵測到 .exe 副檔名                                        │
│       ↓                                                      │
│  /init (WSL 核心) 轉發執行請求                                 │
│       ↓                                                      │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  Windows                                                 │ │
│  │  notepad.exe 啟動                                        │ │
│  │  檔案路徑自動轉換:                                         │ │
│  │  /home/user/file.txt → \\wsl.localhost\Ubuntu\home\...  │ │
│  └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

驗證 Interop 狀態

cat /proc/sys/fs/binfmt_misc/WSLInterop

# 輸出：
# enabled
# interpreter /init
# flags: P
# magic 4d5a    ← MZ header (Windows PE 格式)

常用範例

# 開啟記事本
notepad.exe ~/.bashrc

# 開啟檔案總管
explorer.exe .

# 開啟 VS Code / Antigravity
code .
antigravity .

# 使用 Windows 剪貼簿
cat file.txt | clip.exe              # 複製到剪貼簿
powershell.exe Get-Clipboard         # 從剪貼簿讀取

# 開啟網頁
cmd.exe /c start https://google.com

路徑自動轉換

WSL 會自動將 Linux 路徑轉換為 Windows 可讀的 UNC 路徑：

Linux 路徑 Windows 看到的路徑
/home/user/file.txt \\wsl.localhost\Ubuntu\home\user\file.txt
/mnt/c/Users/ C:\Users\

Linux 與 Windows 應用程式的差異

執行檔格式比較

# 檢查 Linux 應用程式
file $(which thunar)
# 輸出: ELF 64-bit LSB pie executable, x86-64...

# 檢查 Windows 應用程式
file /mnt/c/Windows/System32/notepad.exe
# 輸出: PE32+ executable (GUI) x86-64, for MS Windows...

執行路徑對比

項目 Linux 應用 (如 thunar) Windows 應用 (如 notepad.exe)
執行檔格式 ELF (Linux) PE32+ (Windows)
執行環境 WSL 內部 Windows
顯示方式 WSLg/Wayland → RDP 原生 Windows
觸發機制 直接執行 WSL Interop 轉發

圖示說明

┌─────────────────────────────────────────────────────────────┐
│  在 WSL Terminal 執行...                                     │
│                                                              │
│  $ thunar                    $ notepad.exe                   │
│       ↓                           ↓                          │
│  Linux 執行檔               Windows 執行檔                    │
│       ↓                           ↓                          │
│  WSL 內執行                 WSL Interop 轉發                  │
│       ↓                           ↓                          │
│  Wayland → Weston           Windows 原生執行                  │
│       ↓                           ↓                          │
│  RDP → Windows 顯示          Windows 直接顯示                 │
└─────────────────────────────────────────────────────────────┘

IDE Remote Development 架構

Antigravity / VS Code 連接 WSL 的原理

當你在 WSL 中執行 antigravity . 或 code . 時，實際上啟動的是 Windows 版本的 IDE，透過 Remote Development 模式連接到 WSL。

架構圖

┌────────────────────────────────────────────────────────────────┐
│  Windows 11                                                     │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │  Antigravity.exe (Electron GUI)                            │ │
│  │       ↓                                                    │ │
│  │  透過 WSL Interop 啟動 WSL Server                           │ │
│  └────────────────────────────────────────────────────────────┘ │
│                              ↕ TCP 連線 (127.0.0.1:xxxxx)       │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │  WSL Ubuntu                                                │ │
│  │  ┌──────────────────────────────────────────────────────┐  │ │
│  │  │  Antigravity Server (Node.js)                        │  │ │
│  │  │  位置: ~/.antigravity-server/                        │  │ │
│  │  │  監聽: 127.0.0.1:動態port                             │  │ │
│  │  │                                                      │  │ │
│  │  │  ├── Extension Host                                  │  │ │
│  │  │  │   ├── Language Server                             │  │ │
│  │  │  │   ├── Terminal 控制                                │  │ │
│  │  │  │   └── File Watcher                                │  │ │
│  │  │  │                                                   │  │ │
│  │  │  └── ManagementConnection                            │  │ │
│  │  │       └── 與 Windows GUI 通訊                          │  │ │
│  │  └──────────────────────────────────────────────────────┘  │ │
│  └────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────┘

關鍵檔案位置

檔案/目錄 用途
~/.antigravity-server/bin/ Server 執行檔和 remote-cli
~/.antigravity-server/data/ 設定和快取
~/.antigravity-server/extensions/ WSL 端擴充功能
~/.antigravity-server/.xxx.log Server 日誌
~/.antigravity-server/.xxx.pid Server 進程 ID

remote-cli 內容

cat ~/.antigravity-server/bin/*/bin/remote-cli/antigravity

#!/usr/bin/env sh
ROOT="$(dirname "$(dirname "$(dirname "$(readlink -f "$0")")")")"
CLI_SCRIPT="$ROOT/out/server-cli.js"
"$ROOT/node" "$CLI_SCRIPT" "$APP_NAME" "$VERSION" "$COMMIT" "$EXEC_NAME" "$@"

連接流程詳解

  1. 使用者執行 antigravity .
  2. remote-cli 呼叫 server-cli.js
  3. 檢查是否已有 Server 運行，沒有則啟動
  4. Server 在本機 loopback (127.0.0.1) 上監聽
  5. 通知 Windows Antigravity.exe 連接
  6. Windows GUI 透過 TCP 連接到 WSL Server
  7. 所有檔案操作和終端機命令在 WSL 內執行
  8. 結果透過 TCP 回傳給 Windows GUI 顯示

常見問題與解決方案

Q1: 執行 Linux GUI 應用時出現警告

(thunar:12345): GLib-GIO-CRITICAL **: GFileInfo created without standard::size

解答: 這是非關鍵警告，不影響功能。通常是因為 Windows 掛載的檔案系統 (/mnt/c) 沒有提供完整的檔案資訊。

解決方法 (可選):

thunar 2>/dev/null &

Q2: Nautilus 出現書籤警告

Unable to get contents of the bookmarks file: Error opening file /home/user/.gtk-bookmarks

解決方法:

touch ~/.gtk-bookmarks

Q3: 如何確認應用程式使用 Wayland 還是 X11？

# 強制使用 Wayland
GDK_BACKEND=wayland your-app

# 強制使用 X11
GDK_BACKEND=x11 your-app

Q4: XDG_SESSION_TYPE 為空？

在 WSL 中，XDG_SESSION_TYPE 通常是空的，因為 WSLg 不是傳統的桌面 session。這是正常的，不影響 Wayland 功能。

Q5: 我可以安裝 Linux 原生版本的 Antigravity 嗎？

可以，但需要注意：

總結

WSL 2 + WSLg 提供了強大的 Linux 開發環境整合：

功能 支援狀態
Linux GUI 應用 (Wayland) ✅ 透過 WSLg
Linux GUI 應用 (X11) ✅ 透過 XWayland
執行 Windows 應用 ✅ 透過 WSL Interop
IDE Remote Development ✅ Windows GUI + WSL Server
GPU 加速 ✅ DirectX 整合
音訊 ✅ PulseAudio

這讓開發者可以同時享受 Windows 桌面環境的便利性和 Linux 開發工具的強大功能！

最後更新: 2026-01-10