PX4 WSL2 开发环境搭建笔记

Created on September 23, 2026

2026   ·   PX4   WSL2   Gazebo   SITL   ·   PX4

1. 选型结论

三台机器实测对比（2026-09-23）：

机器 实测配置 结论
Win10 本机（i7-13700F / 32G / RTX 3060） WSL2 2.7.3 + WSLg 1.0.73 已预装，只差发行版 ✅ 开发机
YPC-M3 迷你主机（192.168.137.136） i5-8260U 4C8T / 16G，Ubuntu 26.04，x86_64 ❌ PX4 官方不支持 26.04
Jetson AGX Orin 64GB（192.168.137.240） aarch64，Ubuntu 24.04.5，12 核 / 61G / 931G NVMe 留作机载计算机（arm64 属社区路径）

依据：PX4 官方文档只支持 Ubuntu 24.04 / 22.04（26.04 明确 “not yet supported”）；PX4 另有官方 WSL2 页面（dev team 支持），且 v1.18 起 make upload 通过 Windows COM 口烧录飞控，不需要 usbipd；WSLg 官方支持 Win10 Build 19044+。本机 CPU/内存远强于另两台。

2. WSL2 + Ubuntu 24.04 安装（E 盘）

不走商店安装（避免首次启动交互式 OOBE），直接用官方云镜像 rootfs 导入，全程可自动化：

# 下载 rootfs（USTC 镜像 ~8.5MB/s；SHA256 对照 cloud-images.ubuntu.com/noble/current/SHA256SUMS）
f=noble-server-cloudimg-amd64-root.tar.xz
curl -L -o /e/WSL/noble-root.tar.xz "https://mirrors.ustc.edu.cn/ubuntu-cloud-images/noble/current/$f"
sha256sum /e/WSL/noble-root.tar.xz

# 导入为 WSL2 发行版（tar.xz 可直接导入）
wsl.exe --import Ubuntu-24.04 E:\WSL\Ubuntu-24.04 E:\WSL\noble-root.tar.xz --version 2

初始配置（root 进入一次，然后重启发行版使 systemd 与默认用户生效）：

wsl -d Ubuntu-24.04 -u root -- bash -c '
useradd -m -s /bin/bash -G sudo hxf0223          # 建用户
echo "hxf0223:密码" | chpasswd
printf "[boot]\nsystemd=true\n\n[user]\ndefault=hxf0223\n\n[network]\nhostname=ubuntu2404\n\n[automount]\noptions=\"metadata\"\n" > /etc/wsl.conf
touch /etc/cloud/cloud-init.disabled             # 云镜像禁用 cloud-init
sed -i -E "s#https?://(archive|security)\.ubuntu\.com/ubuntu#https://mirrors.ustc.edu.cn/ubuntu#g" /etc/apt/sources.list.d/ubuntu.sources
echo "hxf0223 ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/hxf0223 && chmod 440 /etc/sudoers.d/hxf0223
'
wsl --terminate Ubuntu-24.04

pip / uv 换清华源：

mkdir -p ~/.config/pip ~/.config/uv
printf "[global]\nindex-url = https://pypi.tuna.tsinghua.edu.cn/simple\n" > ~/.config/pip/pip.conf
printf "[[index]]\nurl = \"https://pypi.tuna.tsinghua.edu.cn/simple\"\ndefault = true\n" > ~/.config/uv/uv.toml

3. 网络与代理

  • GitHub HTTPS 直连不通；本机代理客户端监听 127.0.0.1:7890（需开启”允许局域网连接”）。WSL2 NAT 模式下宿主机即默认网关，WSL 内经 网关IP:7890 使用代理。
  • WSL 重启后网关 IP 会变，装一个登录时自动修正的脚本 /etc/profile.d/git-proxy.sh：
# 内容：
gw=$(ip route show default | awk '{print $3}')
[ -n "$gw" ] && git config --global http.proxy "http://$gw:7890"
  • 代理客户端没开时的备选：ghfast.top 镜像（本文 PX4 2.6G 克隆即经它完成）：
git config --global url."https://ghfast.top/https://github.com/".insteadOf "https://github.com/"
# 恢复直连代理时记得移除：
# git config --global --remove-section url.https://ghfast.top/https://github.com/
  • apt / pip 走国内源保持直连（不过代理）；packages.osrfoundation.org 国内直连可用且速度可接受。

4. PX4 + Gazebo 工具链安装

# 克隆（代理可用时直接走 github；浅克隆含全部子模块，约 2.6G）
git clone --recursive --depth 1 --shallow-submodules -j8 https://github.com/PX4/PX4-Autopilot.git ~/PX4-Autopilot

cd ~/PX4-Autopilot
# ubuntu.sh 带 set -e，且会从 github 下载 ESP32 Xtensa 工具链——先改写成代理前缀，否则脚本会中断
sed -i "s#https://github.com/#https://ghfast.top/https://github.com/#g" Tools/setup/ubuntu.sh

bash Tools/setup/ubuntu.sh
# 完整安装约 20-40 分钟：SITL 依赖 + NuttX 交叉工具链(arm-none-eabi) + ESP32 Xtensa + Gazebo Harmonic

5. 编译与仿真验证

cd ~/PX4-Autopilot
make px4_sitl                    # 仅编译 SITL（1234 个目标）
make px4_sitl gz_x500            # 编译 + 启动 Gazebo 仿真（WSLg 直接弹出仿真窗口）
HEADLESS=1 make px4_sitl gz_x500 # 无界面模式（占用更低）
make px4_fmu-v6x_default         # 真机飞控固件（交叉工具链已装）

启动日志中依次出现以下行即为健康：

INFO  [init] Gazebo world is ready
INFO  [init] Spawning Gazebo model
INFO  [gz_bridge] world: default, model: x500_0
INFO  [tone_alarm] home set      ← GPS + EKF 位置估计正常

6. 已知问题

  • /tmp 是 tmpfs：WSL 发行版空闲自动关机后 /tmp 内容清空，调试日志放 ~ 下。
  • 非交互 stdin 运行 px4：pxh> 提示符会死循环刷出 GB 级日志——自动化场景用 tail -f /dev/null | 挂住 stdin；交互使用无此问题。
  • 不要直接运行 build/px4_sitl_default/bin/px4：缺 make 注入的 GZ 环境变量，会一直 “Waiting for Gazebo world”；始终用 make 入口。
  • GPU：CUDA 直通可用（WSL 内 nvidia-smi 正常）；OpenGL 目前走 llvmpipe 软渲染（Windows 端 NVIDIA 驱动 536.40 太旧，Mesa d3d12 后端初始化失败），升级 Windows 显卡驱动后应可恢复 GPU 加速渲染。llvmpipe 在 24 线程 CPU 上跑 x500 场景够用。
  • QGC（Windows 版）连 SITL：WSL IP 每次重启变化，需在 QGC 手动添加 UDP link 指向 WSL_IP:18570（PX4 官方 WSL 文档做法）。
  • Git Bash 调用 wsl.exe 传含 / 的参数时，先 export MSYS2_ARG_CONV_EXCL='*' 防止路径被 MSYS 改写。

7. 日常使用速查

wsl -d Ubuntu-24.04              # 进入环境（Windows Terminal 会自动出现配置文件）
cd ~/PX4-Autopilot
make px4_sitl gz_x500            # 仿真

磁盘布局：发行版 VHDX 在 E:\WSL\Ubuntu-24.04\（稀疏文件，按需增长）；rootfs 安装包 E:\WSL\noble-root.tar.xz（229M，可删）。

8. 参考资料



Enjoy Reading This Article?

Here are some more articles you might like to read next: