入門教學：在 Windows 用 Docker 與 VS Code 打造專業的 PX4 + ROS2 開發環境（含完全踩坑指南）

如果你曾經在機器人或無人機開發中，為了解決環境依賴衝突、版本不相容，或是那句經典的「在我的電腦上明明可以跑」而耗費數小時，那你絕對需要一套容器化的開發環境。

網路上關於 PX4 與 ROS2 的教學多半以原生 Linux 環境為主。本文參考了 James Odukoya 的優秀架構，並專門針對 Windows 使用者進行了改良與踩坑紀錄。我們將使用 Docker、ROS2 Humble 與 VS Code 的 Dev Containers，一步步打造出乾淨、可重現且支援 Gazebo 3D 模擬畫面的專業開發環境。

做技術研究，我們都不一定總是一次就對，但追求準確與徹底解決問題是開發者的浪漫。以下是經過反覆驗證的完整建置指南。

🛠️ 事前準備工作

在開始之前，請確認你的 Windows 系統已經安裝好以下工具：

1. Docker Desktop (在 Microsoft Store 下載，並確保在背景執行中)
2. Visual Studio Code (VS Code)
3. VS Code 擴充套件：Dev Containers (Microsoft 官方發行)
4. VcXsrv Windows X Server (這是在 Windows 上顯示 Docker 內 Gazebo 模擬器畫面的關鍵，後文會詳細說明)

第一步：建立專案結構與核心環境 (Dockerfile)

建立一個新資料夾（例如 px4_ros2_env），並在其中建立以下檔案結構：

px4_ros2_env/
├── Dockerfile
└── .devcontainer/
    └── devcontainer.json

首先，我們來撰寫環境的靈魂 — — Dockerfile。這份檔案包含了 ROS2 基礎、Gazebo Garden 模擬器，以及 Micro-XRCE-DDS 通訊橋樑。

💡 避坑筆記： 這裡已經特別補上了 future 這個 Python 套件，解決了新版 PX4 編譯時會遇到的 ModuleNotFoundError 錯誤。

# 1. 基礎映像檔：包含完整的 ROS2 Humble 與可視化工具
FROM osrf/ros:humble-desktop-full

# 2. 設定使用者 (避免掛載資料夾時產生權限問題)
ARG USERNAME=developer
ARG USER_UID=1000
ARG USER_GID=$USER_UID

ENV DEBIAN_FRONTEND=noninteractive
ENV LANG=C.UTF-8
ENV LC_ALL=C.UTF-8

# 3. 安裝日常開發會用到的核心工具
RUN apt-get update && apt-get install -y \
    ca-certificates gnupg lsb-release sudo wget curl git vim \
    build-essential cmake python3-pip python-is-python3 gdb valgrind \
    && rm -rf /var/lib/apt/lists/*

# 4. 安裝 PX4 綁定的 Python 依賴
# ⚠️ 注意：empy==3.3.4 是必填版本！並加入了 future 以防編譯報錯
RUN pip3 install --no-cache-dir --upgrade pip && \
    pip3 install --no-cache-dir \
    empy==3.3.4 pyros-genmsg kconfiglib jsonschema jinja2 \
    pyserial pyyaml packaging toml numpy pandas future

# 5. 安裝 Gazebo Garden
RUN wget https://packages.osrfoundation.org/gazebo.gpg -O /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg && \
    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/gazebo-stable.list > /dev/null && \
    apt-get update && apt-get install -y gz-garden && rm -rf /var/lib/apt/lists/*

# 6. 安裝 PX4 其他依賴庫
RUN apt-get update && apt-get install -y \
    astyle lcov libgstreamer-plugins-base1.0-dev \
    gstreamer1.0-plugins-bad gstreamer1.0-plugins-base \
    gstreamer1.0-plugins-good gstreamer1.0-plugins-ugly \
    gstreamer1.0-libav ninja-build protobuf-compiler \
    libeigen3-dev libopencv-dev rsync && rm -rf /var/lib/apt/lists/*

# 7. 關鍵橋樑：編譯 Micro-XRCE-DDS Agent
RUN cd /tmp && \
    git clone https://github.com/eProsima/Micro-XRCE-DDS-Agent.git && \
    cd Micro-XRCE-DDS-Agent && mkdir build && cd build && \
    cmake .. && make && make install && ldconfig /usr/local/lib/ && \
    cd / && rm -rf /tmp/Micro-XRCE-DDS-Agent

# 8. 建立非 root 的 developer 使用者
RUN groupadd --gid $USER_GID $USERNAME \
    && useradd --uid $USER_UID --gid $USER_GID -m $USERNAME -s /bin/bash \
    && echo "$USERNAME:$USERNAME" | chpasswd \
    && echo "$USERNAME ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/$USERNAME \
    && chmod 0440 /etc/sudoers.d/$USERNAME

RUN mkdir -p /home/$USERNAME/workspace && chown -R $USERNAME:$USERNAME /home/$USERNAME
USER $USERNAME
WORKDIR /home/$USERNAME

# 9. 配置 bash 環境變數
RUN echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc && \
    echo "source /usr/share/gazebo/setup.bash" >> ~/.rc && \
    echo "export GZ_SIM_RESOURCE_PATH=\$GZ_SIM_RESOURCE_PATH:/home/$USERNAME/workspace/PX4-Autopilot/Tools/simulation/gz/models" >> ~/.bashrc && \
    echo "export GZ_SIM_SYSTEM_PLUGIN_PATH=\$GZ_SIM_SYSTEM_PLUGIN_PATH:/home/$USERNAME/workspace/PX4-Autopilot/build/px4_sitl_default/build_gz-garden" >> ~/.bashrc

第二步：配置 VS Code Dev Container (Windows 專屬修正)

接下來是 .devcontainer/devcontainer.json 的設定。這個檔案會自動幫你下載 PX4 與 ROS2 的程式碼。

💡 避坑筆記： Windows 並沒有 Linux 的 /tmp/.X11-unix 資料夾，若直接照抄 Linux 的教學，容器會在啟動時直接 Crash (報錯 invalid mount config for type "bind" )。這裡我們移除了該掛載，並將 DISPLAY 環境變數指向 host.docker.internal:0.0，讓容器能找到 Windows 主機的螢幕。

{
    "name": "PX4 ROS2 Development Environment",
    "build": {
        "dockerfile": "../Dockerfile",
        "args": {
            "USERNAME": "developer",
            "USER_UID": "1000",
            "USER_GID": "1000"
        }
    },
    "remoteUser": "developer",
    "containerUser": "developer",
    "workspaceFolder": "/home/developer/workspace",
    "mounts": [
        "source=${localWorkspaceFolder},target=/home/developer/workspace,type=bind"
    ],
    "containerEnv": {
        "DISPLAY": "host.docker.internal:0.0",
        "WORKSPACE_DIR": "/home/developer"
    },
    "runArgs": [
        "--privileged", 
        "--network=host",
        "--gpus=all"
    ],
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-vscode.cpptools-extension-pack",
                "ms-vscode.cmake-tools",
                "ms-python.python",
                "ms-azuretools.vscode-docker",
                "redhat.vscode-yaml"
            ],
            "settings": {
                "terminal.integrated.defaultProfile.linux": "bash",
                "cmake.configureOnOpen": false,
                "python.defaultInterpreterPath": "/usr/bin/python3"
            }
        }
    },
    "postCreateCommand": "bash -c 'cd /home/developer/workspace && if [ ! -d \"PX4-Autopilot\" ]; then git clone -b release/1.14 https://github.com/PX4/PX4-Autopilot.git --recursive; fi && mkdir -p ros2_ws/src && cd ros2_ws/src && if [ ! -d \"px4_msgs\" ]; then git clone -b release/1.14 https://github.com/PX4/px4_msgs.git; fi && if [ ! -d \"px4_ros_com\" ]; then git clone -b release/v1.14 https://github.com/PX4/px4_ros_com.git; fi'"
}

第三步：啟動容器與建立自動化腳本

💡 避坑筆記：在建置前，需要先處理 Windows 環境的問題：Docker 在嘗試拉取映像檔（osrf/ros:humble-desktop-full）時，試圖使用 docker-credential-desktop 這個工具來處理登入驗證，但系統卻找不到這個執行檔。

這在 Windows 環境下的 Docker Desktop 是一個常見的問題。以下是解決這個問題的步驟：

🛠️ 解決方案：修改 Docker 的設定檔

我們需要告訴 Docker 不要再試圖使用那個有問題的憑證小幫手。

1. 開啟 Docker Desktop: 確保你的 Docker Desktop 正在執行。
2. 尋找並開啟 config.json: 這個檔案通常位於你的使用者目錄下。請打開檔案總管，在路徑列輸入以下路徑並按下 Enter： %USERPROFILE%\.docker\config.json （這會帶你到類似 C:\Users\usr_name\.docker\config.json 的地方）
3. 編輯 config.json: 使用任何文字編輯器（例如記事本或 VS Code）打開這個檔案。
4. 修改 credsStore 設定: 你可能會看到類似這樣的內容：

{
  "credsStore": "desktop"
}

請將 credsStore 改名為 credStore（把 s 拿掉），修改後應該會像這樣：

{
  "credStore": "desktop"
}

存檔後， Docker 就能順利繞過憑證錯誤，成功開始拉取 ROS2 的映像檔並進行環境建構了！

解決了 Windows 環境的問題，接下來就能正式啟動容器與建立自動化腳本了。

1. 在 VS Code 按下 Ctrl + Shift + P，輸入並選擇 **Dev Containers: Rebuild and Reopen in Container**。
2. 耐心等待約 10~15 分鐘（初次建置需下載映像檔與龐大的 PX4 專案）。
3. 進入容器後，開啟終端機，執行以下指令來建立自動化腳本，幫助我們省去未來打長串指令的麻煩：

mkdir -p ~/scripts

# 1. 編譯 PX4 韌體
cat > ~/scripts/build_px4.sh << 'EOF'
#!/bin/bash
cd ~/workspace/PX4-Autopilot
make clean
make px4_sitl gz_x500
EOF

# 2. 執行模擬器
cat > ~/scripts/run_simulation.sh << 'EOF'
#!/bin/bash
cd ~/workspace/PX4-Autopilot
make px4_sitl gz_x500
EOF

# 3. 啟動 DDS 代理 (PX4 與 ROS2 的橋樑)
cat > ~/scripts/run_dds_agent.sh << 'EOF'
#!/bin/bash
MicroXRCEAgent udp4 -p 8888
EOF

# 4. 編譯 ROS2 工作區
cat > ~/scripts/build_ros2.sh << 'EOF'
#!/bin/bash
source /opt/ros/humble/setup.bash
cd ~/workspace/ros2_ws
colcon build --symlink-install
source install/setup.bash
EOF

chmod +x ~/scripts/*.sh

第四步：首次編譯 (建議雙開終端機)

因為程式碼龐大，建議在 VS Code 中開啟兩個獨立的終端機平行編譯，節省時間：

• 終端機 1: 執行 ~/scripts/build_px4.sh
• 終端機 2: 執行 ~/scripts/build_ros2.sh

放鬆一下去喝杯水，大約需要 10 到 15 分鐘。

第五步：解決 Windows 模擬器畫面顯示問題 (XLaunch)

要在 Windows 看到 Docker 內的 Gazebo 畫面，必須透過 X Server。請依照以下設定啟動 VcXsrv：

1. 在 Windows 搜尋並啟動 XLaunch。
2. Display settings: Multiple windows -> 下一步。
3. Client startup: Start no client -> 下一步。
4. Extra settings: 務必勾選 Disable access control（不勾的話 Docker 會被防火牆擋在門外跳不出畫面）。
5. 點擊完成（右下角系統匣會出現 X 圖示）。

提醒：每次重新開機後要跑模擬器前，都要記得先開 XLaunch！

🚀 第六步：虛擬起飛！驗收成果

我們現在要模擬實際開發的流程。請在 VS Code 中開啟 3 個獨立的終端機：

終端機 1：啟動模擬器

~/scripts/run_simulation.sh

👉 這時 Gazebo Garden 的畫面應該會跳出來，出現一台無人機。終端機的最後一行會顯示 pxh> 的命令提示字元。

💡 避坑筆記：有可能會出現錯誤，無法順利啟動模擬器，若問題是這行：

*INFO [px4] PX4 server already running for instance 0*

這表示在你的 Docker 容器裡，已經有一個 PX4 的模擬器程序（Instance 0）正在背景執行了。因為它佔用了特定的通訊埠和資源，當你再次輸入 ~/scripts/run_simulation.sh 想要重新啟動時，系統發現資源被佔用，就會報錯並強制停止。

這通常發生在你之前可能不小心按到了執行、或者前一次執行中斷時沒有正常關閉程序。在 Windows 進行這類本地模擬 (SITL) 時，這種通訊埠佔用的情況很常見。

🛠️ 解決方案：殺掉卡住的程序

我們需要手動把卡在背景的 PX4 程序清掉。請在你的終端機輸入以下指令：

killall px4

（如果它顯示 px4: no process found，那就表示 px4 沒有在跑，你可以試試看 pkill -f px4 或是 killall ruby，有時候 Gazebo 的腳本會卡住。）

清掉之後，再次輸入你的執行腳本，這次它應該就能順利啟動一個全新的模擬器了！

終端機 2：啟動通訊橋樑

~/scripts/run_dds_agent.sh

👉 這會啟動 Agent。你應該會看到類似「Client connected」的連線成功訊息。

終端機 3：驗證 ROS2 通訊

source ~/workspace/ros2_ws/install/setup.bash
ros2 topic list

👉 如果你在列表中看到 /fmu/in/vehicle_command 或 /fmu/out/vehicle_status 這類的主題，代表 ROS2 成功讀取到無人機的狀態了！

起飛指令 回到 終端機 1 (pxh> 介面)，輸入：

commander takeoff

🎉 切換到 Gazebo 的視窗，你應該會看到無人機升空了！

🚧 附錄：再次啟動標準作業流程 (SOP)

既然最痛苦的「環境建置」與「首次編譯」都已經完成了，你未來的日常開發流程將會變得非常輕鬆、快速。

你不需要再管 Dockerfile 或是重新下載任何東西。下次當你打開電腦準備開始工作時，請直接按照這個 「日常開發標準作業流程 (SOP)」 執行：

☀️ 步驟一：啟動 Windows 基礎服務 (最容易忘記的一步！)

在打開程式碼之前，請先確保底層服務已經運行：

1. 確認 Docker Desktop 已啟動：檢查右下角系統匣的鯨魚圖示。
2. 啟動 XLaunch (VcXsrv)：

• 打開 XLaunch，一路按下一步。
• ⚠️ 務必再次確認勾選 Disable access control。
• 點擊完成（確認右下角出現 X 圖示）。

💻 步驟二：進入 VS Code 開發環境

1. 打開 VS Code。
2. 透過 檔案 > 開啟資料夾，選擇你的 px4_ros2_env 資料夾。
3. VS Code 通常會記住你上次的狀態並自動在容器中開啟。

• 如果沒有自動開啟，請點擊左下角的 >< 綠色按鈕，或按 Ctrl + Shift + P 選擇 Dev Containers: Reopen in Container。

等待左下角顯示連線成功（因為映像檔都建好了，這通常只需要幾秒鐘）。

🚀 步驟三：啟動你的無人機模擬系統

接下來就跟我們最後測試的步驟一模一樣。請在 VS Code 內開啟三個終端機，依序執行：

終端機 1 (啟動 Gazebo 模擬器與 PX4)：

~/scripts/run_simulation.sh

(等待 Gazebo 畫面彈出)

終端機 2 (啟動通訊橋樑)：

~/scripts/run_dds_agent.sh

終端機 3 (你的主要工作區 / ROS2 開發)：

source ~/workspace/ros2_ws/install/setup.bash

(載入環境後，你就可以在這裡執行 ros2 run 來啟動你自己寫的程式，或是用 ros2 topic echo 來監聽資料了！)

💡 進階提示：什麼時候需要重新編譯？

你在日常啟動時，不需要每次都執行 build_px4.sh 和 build_ros2.sh。

• 只有當你修改了 PX4 Autopilot 裡面的底層 C++ 程式碼：你才需要在終端機執行 ~/scripts/build_px4.sh。
• 只有當你修改了 ROS2 的程式碼 (C++ 或 Python)：你才需要在終端機執行 ~/scripts/build_ros2.sh。

如果只是單純想打開模擬器飛一下、測試現有的功能，直接從步驟三啟動腳本就可以了！

這篇文章記錄了從零到一的環境配置心血，希望能幫到同樣在 Windows 上開發無人機應用的工程師們。Happy Coding & Flying!