教學：在 Windows WSL2 使用 ROS2 Humble Docker 映像搭配 X11 轉發（以 RViz2 驗證）

Context

整理自線上資料與實際操作經驗，建立一份完整的繁體中文教學，說明如何在 Windows WSL2 環境中透過 X11 轉發執行 ROS2 Humble 官方 Docker 映像，並以 RViz2 驗證 GUI 顯示正常運作。

教學正文

前言

在 Windows 上開發 ROS2 有兩種常見路徑：

直接安裝 WSL2 Ubuntu + ROS2（適合長期開發）
WSL2 + Docker 執行官方 ROS2 映像（隔離乾淨、版本切換快）

本教學採用第 2 種路徑：使用 osrf/ros:humble-desktop-full 官方映像，透過 X11 轉發在 Windows 桌面呈現 RViz2 GUI。

環境需求

項目	建議版本
Windows	10 21H2+ 或 Windows 11
WSL2	已啟用，核心 ≥ 5.10
Docker Desktop	已安裝，並設定使用 WSL2 後端
X Server	Windows 11 → 內建 WSLg；Windows 10 → 需安裝 VcXsrv

第一步：確認 WSL2 已啟用

以系統管理員身份開啟 PowerShell，執行：

# 啟用 WSL 與虛擬機器平台
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
 
# 設定預設使用 WSL2
wsl --set-default-version 2
 
# 確認版本
wsl --status

若尚未安裝 Linux 發行版，執行：

wsl --install -d Ubuntu-22.04

第二步：設定 X11 顯示伺服器

方案 A：Windows 11 + WSLg（推薦，零設定）

Windows 11 已內建 WSLg（Windows Subsystem for Linux GUI），提供原生 Wayland/X11 轉發，不需要安裝任何額外 X Server。

驗證 WSLg 是否就緒：

# 在 WSL2 終端執行
echo $DISPLAY          # 應輸出類似 :0
echo $WAYLAND_DISPLAY  # 應輸出 wayland-0
ls /tmp/.X11-unix/     # 應看到 X0

方案 B：Windows 10（需安裝 VcXsrv）

下載並安裝 VcXsrv
從開始選單開啟 XLaunch，設定如下：
- Display Settings：Multiple windows，Display number：0
- Client startup：Start no client
- Extra settings：勾選 Disable access control（重要！）
完成設定後 XLaunch 會在背景執行

在 WSL2 的 ~/.bashrc 加入（每次啟動自動設定 DISPLAY）：

export DISPLAY=$(grep nameserver /etc/resolv.conf | awk '{print $2}'):0
export LIBGL_ALWAYS_INDIRECT=1

套用設定：

source ~/.bashrc

第三步：拉取 ROS2 Humble 官方映像

在 WSL2 終端（或 Windows PowerShell，Docker Desktop 已整合）執行：

docker pull osrf/ros:humble-desktop-full

humble-desktop-full 包含完整桌面工具組，含 RViz2、rqt、Gazebo 等，映像約 3–4 GB。

第四步：建立 docker-compose.yml 並啟動容器

在專案目錄下建立 docker-compose.yml。兩種環境的設定略有不同，選擇對應的版本即可。

Windows 11 / WSLg

WSLg 透過 Unix socket 共享顯示，掛載 /tmp/.X11-unix 與 /mnt/wslg：

services:
  ros2:
    image: osrf/ros:humble-desktop-full
    container_name: ros2_humble
    environment:
      - DISPLAY=${DISPLAY}
      - WAYLAND_DISPLAY=${WAYLAND_DISPLAY}
      - XDG_RUNTIME_DIR=/tmp
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix:rw
      - /mnt/wslg:/mnt/wslg
      - ./workspace:/root/ws
    stdin_open: true
    tty: true
    network_mode: host
    command: bash

啟動：

docker compose run --rm ros2

Windows 10 / VcXsrv

VcXsrv 透過 TCP 接收連線，DISPLAY 指向 host.docker.internal：

services:
  ros2:
    image: osrf/ros:humble-desktop-full
    container_name: ros2_humble
    environment:
      - DISPLAY=host.docker.internal:0.0
      - LIBGL_ALWAYS_INDIRECT=0
    volumes:
      - ./workspace:/root/ws
    stdin_open: true
    tty: true
    command: bash

啟動（Windows 10 不使用 network_mode: host，因為 Docker Desktop 的 host 模式不等同 Windows 主機網路）：

docker compose run --rm ros2

Tip： ./workspace 目錄會掛載到容器內的 /root/ws，可在此放置 ROS2 工作區，重啟容器後資料不會遺失。

第五步：在容器內啟動 RViz2 驗證

進入容器後，先 source ROS2 環境：

source /opt/ros/humble/setup.bash

啟動 RViz2：

rviz2

若設定正確，RViz2 視窗會在 Windows 桌面彈出。

常見驗證步驟：

# 確認 ROS2 環境
ros2 --version          # 應顯示 humble
 
# 查看 topic 清單
ros2 topic list
 
# 發布測試 TF 並在 RViz2 觀察
ros2 run tf2_ros static_transform_publisher 1 0 0 0 0 0 world base_link

常見問題排解

症狀	原因	解法
`cannot connect to X server`	DISPLAY 未設定或 X Server 未啟動	確認 `echo $DISPLAY` 有值；重啟 XLaunch
RViz2 視窗閃退	OpenGL 問題	加入 `-e LIBGL_ALWAYS_INDIRECT=1`
WSLg 無法使用	WSL 核心太舊	執行 `wsl --update`
Docker 看不到 GPU	需要 GPU 加速	加入 `--gpus all`（需 NVIDIA Container Toolkit）
Windows 防火牆擋住	VcXsrv 連線被阻	在 Windows 防火牆允許 VcXsrv 的公共網路存取

Key Insights

Windows 11 + WSLg 是目前最簡單的 ROS2 GUI 方案，不需要任何 X Server 設定
Windows 10 使用 VcXsrv 時，Disable access control 是最常遺漏的關鍵設定
host.docker.internal:0.0 是 Docker Desktop for Windows 的特殊 hostname，讓容器連回 Windows 的 X Server
WSLg 透過 Unix socket（/tmp/.X11-unix）和 /mnt/wslg 掛載共享顯示，效能優於 TCP 轉發
osrf/ros:humble-desktop-full 映像已包含 RViz2，無需額外安裝

Quartz 5

Explorer