Ubuntu 24.04安装PX4这件事网上教程一搜一大把但很多教程要么停留在Ubuntu 18.04/20.04的旧时代要么直接搬运官方文档中间隔着好几个坑。我最近在24.04上从零搭了一遍PX4开发环境把踩过的坑和验证过的步骤都记下来了。这篇主要讲环境准备到源码编译跑通仿真适合刚接触飞控开发、准备在Ubuntu 24.04上搭PX4环境的同学也适合被各种依赖问题折磨到想放弃的老哥。1. 为什么选Ubuntu 24.04以及装系统前必须想清楚的两件事先聊一个很多人忽略的问题现在网上大量PX4教程还是基于Ubuntu 20.04甚至18.04写的。22.04的教程都不算多24.04作为2024年发布的LTS版本官方支持肯定没问题但不少老教程里的依赖安装命令在24.04上会报错原因是Python版本变了、某些软件源里的包名变了、gcc版本也换了。1.1 Ubuntu 24.04对PX4开发的实际价值24.04自带的是Python 3.12、GCC 13、CMake 3.28这些版本对于PX4 1.15及以后的版本来说都是新过头但能用的状态。PX4官方从1.14开始逐步完善对新版Ubuntu的支持到1.15版本已经可以把工具链安装脚本跑得很顺。24.04相比20.04/22.04的实际好处新硬件支持更好尤其是近两年的笔记本网卡、显卡驱动不用折腾GCC 13对C20的支持非常完善PX4的代码编译起来更顺ROS 2 Humble官方支持Ubuntu 22.04但24.04上装Humble也能跑只是需要一点额外操作软件源里很多工具版本都很新不用手动编译1.2 装系统前先做两个决定第一个决定是装双系统还是用虚拟机如果你只是学习PX4的代码结构、跑跑仿真虚拟机完全够用。但如果要接地面站、调参、后续接GPS和遥控器或者准备编译完固件刷到真机上建议直接双系统。虚拟机在USB设备透传上偶尔会出幺蛾子Pixhawk的USB识别在虚拟机里虽然基本没问题但等你开始用串口调试、连接数传模块时双系统会省掉大量跟USB passthrough搏斗的时间。第二个决定交换分区/交换文件要给够。PX4编译时非常吃内存我实测在一台16GB内存的机器上编译PX4固件峰值内存占用能到6-8GB。如果你用虚拟机装Ubuntu 24.04建议给至少8GB内存并设置8GB以上的交换空间。否则编译到一半直接OOM进程被杀你会误以为是代码问题实际上就是内存不够。我自己的建议配置物理机16GB内存起磁盘剩余空间至少50GB虚拟机内存8GB磁盘动态分配40GB交换空间8GBCPU核数影响很大多核编译能显著加速有4核以上最好另外提醒一句如果你用的是虚拟机VMware或VirtualBox的3D加速对Ubuntu 24.04的默认桌面环境GNOME来说体验一般。如果感觉界面卡顿可以在虚拟机设置里把显存调大或者直接换用Xubuntu的桌面环境编译效率会高一些。2. 系统基础配置换源、SSH、必要软件这三步直接影响你后面顺不顺Ubuntu 24.04装好之后先别急着装PX4。先把系统基础调校好不然你会在各种莫名其妙的地方卡住。2.1 换软件源是第一步也是最重要的一步国内用户如果不换源直接跑PX4的依赖安装脚本你会发现下载速度可能只有几十KB/s装一个依赖要等十几分钟极其煎熬。Ubuntu 24.04的软件源配置文件路径和旧版本不太一样需要注意。24.04使用APT源管理方式源文件在/etc/apt/sources.list.d/ubuntu.sources不再是以前的/etc/apt/sources.list。这是24.04一个明显变化。换源操作很直接把ubuntu.sources里的源地址换成国内镜像。推荐用清华、阿里或中科大的镜像源我一般用清华源稳定性很好。# 备份原文件 sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak # 编辑源文件 sudo nano /etc/apt/sources.list.d/ubuntu.sources把文件里的http://archive.ubuntu.com/ubuntu/全部替换为https://mirrors.tuna.tsinghua.edu.cn/ubuntu/http://security.ubuntu.com/ubuntu/替换为https://mirrors.tuna.tsinghua.edu.cn/ubuntu/。替换完成后执行sudo apt update sudo apt upgrade -y这里有个细节你可能会在网络上看到一些教程叫你用sed命令批量替换但我建议手动打开文件看清楚再改因为24.04的源文件格式变了不是简单的deb开头行而是带Types:、URIs:这种类似YAML的格式无脑sed容易出错。2.2 开启SSH服务省去来回插显示器的麻烦开发飞控环境时我习惯远程操作——笔记本放在一旁通过SSH连接开发机或者用VS Code的Remote插件连接这样无论在哪都能继续开发。sudo apt install openssh-server -y sudo systemctl enable ssh --now查看一下开发机的IP地址使用ip addr命令。然后从另一台机器连接ssh 用户名IP地址2.3 安装基础软件包vim、net-tools、curl等这些不一定全用得上但装上没坏处sudo apt install -y vim git curl wget net-tools htophtop对监控编译时的系统资源很有用编译时开一个终端看内存和CPU能及时发现资源不足的情况。2.4 关于中文输入法的选择热搜词里有人提到Ubuntu 24.04 config chinese input source这确实是很多人装完系统后第一个遇到的问题。Ubuntu 24.04默认输入法框架是IBus在设置里添加中文拼音输入法后有时会遇到无法调出输入框的情况。经验做法安装fcitx5稳定性比IBus在处理某些应用时更好尤其是微信Linux版、WPS这类需要输入法的应用。sudo apt install -y fcitx5 fcitx5-chinese-addons sudo im-config -n fcitx5重启后按CtrlSpace切换输入法。如果重启后仍无法输入中文检查~/.xinputrc文件内容确认是否指向了fcitx5没指向的话手动改成run_im fcitx5。这个坑在24.04上比较常见。3. 核心工具链安装Git、Python、CMake装不对后面全是泪PX4 开发环境的核心依赖包括Git、Python、CMake以及一系列编译工具gcc、g、ninja-build等。PX4官方推荐使用ubuntu_sim_common_deps.sh脚本一键安装但如果不懂每一步在做什么遇到问题排查起来会很头大。所以我还是建议先手动装关键工具再跑脚本补全这样出了问题心里有底。3.1 Git的安装与配置Git 在 Ubuntu 24.04 默认源里的版本是2.43.x对PX4开发来说足够了。sudo apt install -y git安装完建议配置用户名和邮箱不然之后提交代码或者执行某些需要识别身份的操作时会报错git config --global user.name 你的名字 git config --global user.email 你的邮箱还有一个非常关键但容易被忽略的配置filemode。如果你把仓库放到NTFS挂载分区或某些网络文件系统上Git会频繁提示文件权限变更导致git status显示一堆无意义的修改。执行以下命令避免这个问题git config --global core.filemode false另外如果你在GitHub上拉取代码速度慢或无法连接可以尝试配置代理但这不是必须的。后面下载PX4源码时如果直接git clone实在慢可以改用镜像源。3.2 Python环境的正确理解PX4的构建系统大量使用Python脚本但这里有个容易踩坑的地方不要手动把系统默认Python改成某个特定版本也不要轻易用update-alternatives切换Python版本。Ubuntu 24.04自带Python 3.12PX4官方工具链脚本对Python 3.8都能支持3.12完全没问题。真正的坑在于PX4构建过程中会用到pip安装Python包默认情况下Ubuntu 24.04的pip安装会触发externally-managed-environment报错这是PEP 668的规定提示你不能用pip直接装到系统Python里。解决这个问题有几种方式我推荐用虚拟环境或者直接给pip加--break-system-packages参数仅限在容器或虚拟机里这么干物理机上建议用虚拟环境。方式一用虚拟环境推荐PX4官方脚本其实已经在内部处理了部分Python包安装但如果你后续要装numpy、pyulog、empy之类的包建议创建一个虚拟环境sudo apt install -y python3-venv python3-pip mkdir ~/px4_venv python3 -m venv ~/px4_venv source ~/px4_venv/bin/activate pip install --upgrade pip之后所有需要Python包的编译步骤先激活虚拟环境再执行。方式二直接绕过限制谨慎使用如果你确定不会搞乱系统Python可以在pip命令后加--break-system-packages参数pip install --break-system-packages empy3.3.4注意empy这个包版本很关键。PX4构建系统依赖em命令来自empy包4.x版本的empy可能会导致构建失败建议按官方要求用3.3.4版本。这个坑我在PX4 1.14版本上遇到过升级empy到4.x后em命令无法正常处理模板文件编译报错。3.3 CMake、Ninja和编译链Ubuntu 24.04 默认的CMake版本是3.28满足PX4需要要求CMake 3.16。直接安装即可sudo apt install -y cmake ninja-build gcc g gdbPX4支持用Make或Ninja两种构建系统Ninja的并行编译速度更快推荐使用。检查一下版本cmake --version ninja --version gcc --version确认都能正常输出版本信息后基础工具链就绪。3.4 其他系统依赖PX4编译还需要一些系统库例如libgstreamer1.0-dev、libgstreamer-plugins-base1.0-dev仿真和相机相关、libjson-c-dev等。这些在官方脚本里都有如果只装基础依赖可以用以下命令安装一部分sudo apt install -y \ libgstreamer1.0-dev \ libgstreamer-plugins-base1.0-dev \ libjson-c-dev \ libzmq3-dev \ openocd \ ninja-build \ protobuf-compiler \ python3-empy这里特别注意python3-empy这个包Ubuntu 24.04 软件源里可能没有它或者版本是4.x用pip安装3.3.4版本更稳妥。4. PX4源码获取与编译从git clone到第一个固件生成环境准备就绪后就开始拉取PX4源码。这里有几个关键选择下载哪个分支、用哪个镜像、编译哪个目标机型。4.1 选分支main还是releasePX4的官方仓库地址是https://github.com/PX4/PX4-Autopilot.git。截至2025年PX4稳定版本已经到2.x但很多教程基于v1.15或v1.14。作为入门学习我强烈建议不要用main分支可能不稳定选一个release版本分支最省心。cd ~ git clone https://github.com/PX4/PX4-Autopilot.git --recursive cd PX4-Autopilot git checkout v1.15.4 git submodule update --init --recursive4.2 国内拉取慢的替代方案直连GitHub拉取PX4仓库包括所有子模块数据量达到数GB网络不好的话可能要拉好几个小时甚至失败。替代方案是用GitHub镜像站比如gitclone.com或者ghproxy。git clone https://gitclone.com/github.com/PX4/PX4-Autopilot.git --recursive不过镜像站的子模块同步不一定完整clone完成后一定要执行git submodule update --init --recursive确保子模块都拉取完整。如果没有完整拉取编译时会报TinyXML或uavcan之类找不到头文件的错误。4.3 首次编译 Pixhawk 固件PX4支持多种目标硬件入门学习建议编译Pixhawk 4FMUv5或Pixhawk 6XFMUv6X的固件。编译命令格是make px4_fmu-v5_default首次编译需要下载许多第三方依赖比如Firmware工具链、NuttX RTOS等所以时间会比较长在性能较好的机器上大概需要15-30分钟慢的机器可能需要一小时以上。如果要启用Ninja加速构建设置环境变量export PX4_USE_NINJA1建议把这行加到~/.bashrc里这样每次终端打开就自动生效。Ninja的并行度默认根据CPU核心数自动分配不用手动指定-j参数。4.4 针对24.04的编译配置调整如果在编译时遇到gcc: internal compiler error或者某些头文件报错如bits/cconfig.h找不到多半是GCC版本与某些旧代码不兼容。v1.15版本的PX4对GCC 13支持还可以但确实会遇到个别情况经验处理方式方式一切换到GCC 12Ubuntu 24.04仓库里有GCC 12可以安装并切换默认版本sudo apt install -y gcc-12 g-12 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 100 sudo update-alternatives --install /usr/bin/g g /usr/bin/g-12 100方式二换用Docker编译如果GCC切换后问题依旧考虑用PX4官方的Docker镜像。但如果是纯入门学习Docker会带来额外的容器内设备映射、图形界面等复杂度建议先尝试GCC版本切换。4.5 编译成功的标志编译结束后产出文件在build/px4_fmu-v5_default/目录下重点看px4_fmu-v5_default.px4可用于QGroundControl地面站刷写的固件文件px4_fmu-v5_default.bin原始二进制固件px4可执行的仿真程序如果编译了仿真目标如果这个固件文件生成了说明工具链基本没问题PX4核心编译已经通过。5. 跑通 Gazebo 仿真验证PX4安装成功的最快方式编译完固件只成功了一半真正能证明环境完整、可以开始飞控开发的是跑通仿真。PX4的仿真环境基于Gazebo在Ubuntu 24.04上配置Gazebo有些细节需要注意。5.1 安装GazeboHonu即Gazebo 11PX4 v1.15使用的仿真器主要是Gazebo Classic即Gazebo 11。Ubuntu 24.04默认软件源不再提供Gazebo Classic需要添加OSRF软件源sudo apt install -y lsb-release wget gnupg sudo 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 | sudo tee /etc/apt/sources.list.d/gazebo-stable.list sudo apt update sudo apt install -y gazebo11 libgazebo11-dev5.2 安装PX4仿真依赖进入PX4源码目录运行官方仿真依赖脚本cd ~/PX4-Autopilot bash ./Tools/setup/ubuntu.sh --sim这个脚本会安装PX4仿真所需的全部依赖包括Gazebo插件、MAVSDK等。执行时间会比较长过程中如果遇到pip报错就按前面说的加--break-system-packages或先激活虚拟环境。如果脚本执行失败或超时也可以手动安装Gazebo插件依赖sudo apt install -y \ libgazebo11-dev \ protobuf-compiler \ libeigen3-dev \ libopencv-dev \ libboost-all-dev5.3 运行PX4仿真并连接QGroundControl安装完成后启动Gazebo仿真cd ~/PX4-Autopilot make px4_sitl gazebo-classic这个命令会编译SITL软件在环仿真固件然后启动Gazebo界面显示一架四旋翼无人机模型同时终端会启动PX4的SITL进程输出pxh命令行提示符。在pxh命令行里输入commander takeoff可以测试起飞指令。正常情况无人机会起飞到一定高度悬停。再用QGroundControl地面站连接地面站会自动识别到UDP :14550端口上的PX4 SITL实例显示无人机状态和传感器数据。能在地面站上看到姿态信息和位置信息说明PX4环境彻底跑通了。5.4 24.04上运行Gazebo的性能问题在Ubuntu 24.04的虚拟机上跑Gazebo可能会遇到图形渲染特别卡的情况这很常见。解决方法有几个确保VMware或VirtualBox已经安装并启用3D加速将Gazebo环境变量设为使用较低画质export GAZEBO_MODEL_DATABASE_URI跳过在线模型下载关闭Gazebo的GUI用无界面模式gzserver运行仿真只保留PX4 SITL在跑我建议入门阶段直接把Gazebo窗口开起来看视觉效果对理解无人机姿态变化很有帮助卡一点也能接受。5.5 运行offboard模式或MAVSDK示例仿真跑通后可以尝试用MAVSDK-Python写一个简单的起飞脚本验证MAVSDK和PX4仿真之间的通信。pip install --break-system-packages mavsdk然后在另一个终端里运行一个简单Python脚本让无人机起飞import asyncio from mavsdk import System async def run(): drone System() await drone.connect(system_addressudp://:14540) print(Waiting for drone to connect...) async for state in drone.core.connection_state(): if state.is_connected: print(Drone discovered) break print(Waiting for drone to have a global position estimate...) async for health in drone.telemetry.health(): if health.is_global_position_ready and health.is_home_position_ready: print(Global position estimate ready) break print(Arming...) await drone.action.arm() print(Taking off...) await drone.action.takeoff() await asyncio.sleep(10) print(Landing...) await drone.action.land() asyncio.run(run())运行之前需要先在pxh命令行里把SITL设为offboard模式兼容。不过在入门阶段这个脚本不跑也没关系能在地面站看到数据已经算是成功了一大半。6. 环境验证清单跑完以下检查你的PXE开发环境才算真到位很多人装完环境以为能编译就算完成实际上编译通过、仿真能跑、代码能改这三者完全不是一回事。我建议按下面的清单逐项验证确保开发环境真正可用。[ ]git --version、python3 --version、cmake --version输出正常[ ]cd ~/PX4-Autopilot make px4_fmu-v5_default成功生成.px4固件文件[ ]make px4_sitl gazebo-classic能启动Gazebo窗口终端出现pxh提示符[ ] QGroundControl能通过UDP连接SITL地图上能看到无人机位置[ ] 在pxh中输入param set MAV_SYS_ID 2能正常设置参数不报错[ ]git status在PX4源码目录下不显示大量未提交的修改如果以上检查全部通过就可以开始后续的学习了比如阅读PX4模块源码、编写自定义飞行模式、添加传感器驱动等。如果某些检查失败不要急着重装系统。99%的问题出在依赖版本冲突或环境变量配置上按前面提到的排查方式逐一排除即可。记住环境搭建最忌讳的就是反复重装系统那不是解决问题只是把问题推迟到下一次。我自己的经验是环境搭建阶段遇到问题先检查三个地方第一Python相关包的版本第二CMake和编译器版本第三Git子模块是否完整。这三点占掉了PX4安装类问题的大半原因。7. 避坑总结我在Ubuntu 24.04上装PX4踩过的12个具体问题把这一路上的坑集中整理一下方便遇到问题时直接索引。7.1 依赖安装阶段的问题问题根因解决方案pip安装报externally-managed-environmentPEP 668pip命令加--break-system-packages或使用虚拟环境empy版本过高导致构建失败empy 4.x不兼容pip install empy3.3.4apt update卡死或404源文件格式不匹配检查/etc/apt/sources.list.d/ubuntu.sources是否配置正确gcc: internal compiler errorGCC 13兼容性问题切换到GCC 12submodule拉取超时网络问题使用镜像仓库后执行git submodule update --init --recursive7.2 编译阶段的问题问题根因解决方案编译过程中OOM内存不足增加交换空间或降低并行度framework/...头文件找不到子模块不完整git submodule update --init --recursivePX4-Autopilot/Tools/setup/ubuntu.sh执行到一半失败某个依赖安装失败检查报错依赖手动安装后重新执行脚本7.3 仿真阶段的问题问题根因解决方案Gazebo窗口黑屏GPU驱动或VM 3D加速不足开启虚拟机的3D加速物理机安装GPU驱动Gazebo模型只有地面没有无人机模型库加载异常检查~/.gazebo/models模型缓存或重新执行make px4_sitl gazebo-classicQGroundControl连不上SITLUDP端口不匹配确认QGC使用UDP端口14550或手动在pxh里连MAVLinkSITL启动报Missing gazebo model模型文件路径错误确认PX4_SITL_WORLD和PX4_SITL_MODEL环境变量正确7.4 一个容易忽略的问题磁盘空间PX4源码含子模块加上编译产物再加上Gazebo模型库总占用可能会超过20GB。如果磁盘空间不足编译会报各种奇怪的错误比如No space left on device。入门阶段最好预留至少30GB空间。检查方法df -h du -sh ~/PX4-Autopilot如果发现空间不足清理编译缓存make clean或者删除旧的编译目录build/需要时重新编译。8. 环境搭好之后下一步学什么环境搭好只是万里长征第一步。很多人装好环境、跑通仿真然后就开始迷茫接下来该干什么我的建议是按以下顺序继续推进第一学PX4源码结构。PX4的源码组织很清晰src/modules下是各个模块比如mc_pos_control是多旋翼位置控制、mc_att_control是姿态控制、navigator是导航逻辑。花点时间熟悉每个模块的职责和它们之间的消息通信机制uORB这是看懂PX4后续一切内容的基础。第二学uORB消息机制。PX4内部模块之间通过uORB发布/订阅消息通信。在msg/目录下可以看到所有消息定义比如vehicle_attitude.msg、vehicle_local_position.msg。理解了这个机制你才能写自己的模块并接入PX4系统。第三改一个简单模块试试。比如把一个现有模块的日志输出改一下重新编译烧写看看改动有没有生效。这个过程会逼你把编译、烧写、调试整个链路走通。第四接真机。买一块Pixhawk 6C或者类似的飞控板在QGroundControl上刷入自己编译的固件然后找一个安全的空旷场地试飞。真机上遇到的问题比如磁力计校准、电调校准、PID调参是仿真模拟不了的这才是飞控开发真正的魅力所在。我不建议一上来就折腾各种高级功能比如视觉避障、SLAM、集群控制。那些都是在基础链路非常熟练之后才能涉及的领域。先把改代码-编译-刷固件-验证这个闭环跑顺再谈别的。另外有条件的话强烈建议把~/.bashrc里加上以下几行减少很多重复工作export PX4_USE_NINJA1 source ~/px4_venv/bin/activate这样每次打开新终端都自动启用Ninja编译和Python虚拟环境不用每次都手敲一遍。环境搭建这个阶段折磨人的程度和后面上手飞控开发的爽快感成正比。别急着放弃也别急着跳过任何一步。把这篇里的步骤一步步走一遍该踩的坑踩完后面的路会顺很多。 Ubuntu 24.04安装PX4开发环境完整指南
Ubuntu 24.04安装PX4这件事网上教程一搜一大把但很多教程要么停留在Ubuntu 18.04/20.04的旧时代要么直接搬运官方文档中间隔着好几个坑。我最近在24.04上从零搭了一遍PX4开发环境把踩过的坑和验证过的步骤都记下来了。这篇主要讲环境准备到源码编译跑通仿真适合刚接触飞控开发、准备在Ubuntu 24.04上搭PX4环境的同学也适合被各种依赖问题折磨到想放弃的老哥。1. 为什么选Ubuntu 24.04以及装系统前必须想清楚的两件事先聊一个很多人忽略的问题现在网上大量PX4教程还是基于Ubuntu 20.04甚至18.04写的。22.04的教程都不算多24.04作为2024年发布的LTS版本官方支持肯定没问题但不少老教程里的依赖安装命令在24.04上会报错原因是Python版本变了、某些软件源里的包名变了、gcc版本也换了。1.1 Ubuntu 24.04对PX4开发的实际价值24.04自带的是Python 3.12、GCC 13、CMake 3.28这些版本对于PX4 1.15及以后的版本来说都是新过头但能用的状态。PX4官方从1.14开始逐步完善对新版Ubuntu的支持到1.15版本已经可以把工具链安装脚本跑得很顺。24.04相比20.04/22.04的实际好处新硬件支持更好尤其是近两年的笔记本网卡、显卡驱动不用折腾GCC 13对C20的支持非常完善PX4的代码编译起来更顺ROS 2 Humble官方支持Ubuntu 22.04但24.04上装Humble也能跑只是需要一点额外操作软件源里很多工具版本都很新不用手动编译1.2 装系统前先做两个决定第一个决定是装双系统还是用虚拟机如果你只是学习PX4的代码结构、跑跑仿真虚拟机完全够用。但如果要接地面站、调参、后续接GPS和遥控器或者准备编译完固件刷到真机上建议直接双系统。虚拟机在USB设备透传上偶尔会出幺蛾子Pixhawk的USB识别在虚拟机里虽然基本没问题但等你开始用串口调试、连接数传模块时双系统会省掉大量跟USB passthrough搏斗的时间。第二个决定交换分区/交换文件要给够。PX4编译时非常吃内存我实测在一台16GB内存的机器上编译PX4固件峰值内存占用能到6-8GB。如果你用虚拟机装Ubuntu 24.04建议给至少8GB内存并设置8GB以上的交换空间。否则编译到一半直接OOM进程被杀你会误以为是代码问题实际上就是内存不够。我自己的建议配置物理机16GB内存起磁盘剩余空间至少50GB虚拟机内存8GB磁盘动态分配40GB交换空间8GBCPU核数影响很大多核编译能显著加速有4核以上最好另外提醒一句如果你用的是虚拟机VMware或VirtualBox的3D加速对Ubuntu 24.04的默认桌面环境GNOME来说体验一般。如果感觉界面卡顿可以在虚拟机设置里把显存调大或者直接换用Xubuntu的桌面环境编译效率会高一些。2. 系统基础配置换源、SSH、必要软件这三步直接影响你后面顺不顺Ubuntu 24.04装好之后先别急着装PX4。先把系统基础调校好不然你会在各种莫名其妙的地方卡住。2.1 换软件源是第一步也是最重要的一步国内用户如果不换源直接跑PX4的依赖安装脚本你会发现下载速度可能只有几十KB/s装一个依赖要等十几分钟极其煎熬。Ubuntu 24.04的软件源配置文件路径和旧版本不太一样需要注意。24.04使用APT源管理方式源文件在/etc/apt/sources.list.d/ubuntu.sources不再是以前的/etc/apt/sources.list。这是24.04一个明显变化。换源操作很直接把ubuntu.sources里的源地址换成国内镜像。推荐用清华、阿里或中科大的镜像源我一般用清华源稳定性很好。# 备份原文件 sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak # 编辑源文件 sudo nano /etc/apt/sources.list.d/ubuntu.sources把文件里的http://archive.ubuntu.com/ubuntu/全部替换为https://mirrors.tuna.tsinghua.edu.cn/ubuntu/http://security.ubuntu.com/ubuntu/替换为https://mirrors.tuna.tsinghua.edu.cn/ubuntu/。替换完成后执行sudo apt update sudo apt upgrade -y这里有个细节你可能会在网络上看到一些教程叫你用sed命令批量替换但我建议手动打开文件看清楚再改因为24.04的源文件格式变了不是简单的deb开头行而是带Types:、URIs:这种类似YAML的格式无脑sed容易出错。2.2 开启SSH服务省去来回插显示器的麻烦开发飞控环境时我习惯远程操作——笔记本放在一旁通过SSH连接开发机或者用VS Code的Remote插件连接这样无论在哪都能继续开发。sudo apt install openssh-server -y sudo systemctl enable ssh --now查看一下开发机的IP地址使用ip addr命令。然后从另一台机器连接ssh 用户名IP地址2.3 安装基础软件包vim、net-tools、curl等这些不一定全用得上但装上没坏处sudo apt install -y vim git curl wget net-tools htophtop对监控编译时的系统资源很有用编译时开一个终端看内存和CPU能及时发现资源不足的情况。2.4 关于中文输入法的选择热搜词里有人提到Ubuntu 24.04 config chinese input source这确实是很多人装完系统后第一个遇到的问题。Ubuntu 24.04默认输入法框架是IBus在设置里添加中文拼音输入法后有时会遇到无法调出输入框的情况。经验做法安装fcitx5稳定性比IBus在处理某些应用时更好尤其是微信Linux版、WPS这类需要输入法的应用。sudo apt install -y fcitx5 fcitx5-chinese-addons sudo im-config -n fcitx5重启后按CtrlSpace切换输入法。如果重启后仍无法输入中文检查~/.xinputrc文件内容确认是否指向了fcitx5没指向的话手动改成run_im fcitx5。这个坑在24.04上比较常见。3. 核心工具链安装Git、Python、CMake装不对后面全是泪PX4 开发环境的核心依赖包括Git、Python、CMake以及一系列编译工具gcc、g、ninja-build等。PX4官方推荐使用ubuntu_sim_common_deps.sh脚本一键安装但如果不懂每一步在做什么遇到问题排查起来会很头大。所以我还是建议先手动装关键工具再跑脚本补全这样出了问题心里有底。3.1 Git的安装与配置Git 在 Ubuntu 24.04 默认源里的版本是2.43.x对PX4开发来说足够了。sudo apt install -y git安装完建议配置用户名和邮箱不然之后提交代码或者执行某些需要识别身份的操作时会报错git config --global user.name 你的名字 git config --global user.email 你的邮箱还有一个非常关键但容易被忽略的配置filemode。如果你把仓库放到NTFS挂载分区或某些网络文件系统上Git会频繁提示文件权限变更导致git status显示一堆无意义的修改。执行以下命令避免这个问题git config --global core.filemode false另外如果你在GitHub上拉取代码速度慢或无法连接可以尝试配置代理但这不是必须的。后面下载PX4源码时如果直接git clone实在慢可以改用镜像源。3.2 Python环境的正确理解PX4的构建系统大量使用Python脚本但这里有个容易踩坑的地方不要手动把系统默认Python改成某个特定版本也不要轻易用update-alternatives切换Python版本。Ubuntu 24.04自带Python 3.12PX4官方工具链脚本对Python 3.8都能支持3.12完全没问题。真正的坑在于PX4构建过程中会用到pip安装Python包默认情况下Ubuntu 24.04的pip安装会触发externally-managed-environment报错这是PEP 668的规定提示你不能用pip直接装到系统Python里。解决这个问题有几种方式我推荐用虚拟环境或者直接给pip加--break-system-packages参数仅限在容器或虚拟机里这么干物理机上建议用虚拟环境。方式一用虚拟环境推荐PX4官方脚本其实已经在内部处理了部分Python包安装但如果你后续要装numpy、pyulog、empy之类的包建议创建一个虚拟环境sudo apt install -y python3-venv python3-pip mkdir ~/px4_venv python3 -m venv ~/px4_venv source ~/px4_venv/bin/activate pip install --upgrade pip之后所有需要Python包的编译步骤先激活虚拟环境再执行。方式二直接绕过限制谨慎使用如果你确定不会搞乱系统Python可以在pip命令后加--break-system-packages参数pip install --break-system-packages empy3.3.4注意empy这个包版本很关键。PX4构建系统依赖em命令来自empy包4.x版本的empy可能会导致构建失败建议按官方要求用3.3.4版本。这个坑我在PX4 1.14版本上遇到过升级empy到4.x后em命令无法正常处理模板文件编译报错。3.3 CMake、Ninja和编译链Ubuntu 24.04 默认的CMake版本是3.28满足PX4需要要求CMake 3.16。直接安装即可sudo apt install -y cmake ninja-build gcc g gdbPX4支持用Make或Ninja两种构建系统Ninja的并行编译速度更快推荐使用。检查一下版本cmake --version ninja --version gcc --version确认都能正常输出版本信息后基础工具链就绪。3.4 其他系统依赖PX4编译还需要一些系统库例如libgstreamer1.0-dev、libgstreamer-plugins-base1.0-dev仿真和相机相关、libjson-c-dev等。这些在官方脚本里都有如果只装基础依赖可以用以下命令安装一部分sudo apt install -y \ libgstreamer1.0-dev \ libgstreamer-plugins-base1.0-dev \ libjson-c-dev \ libzmq3-dev \ openocd \ ninja-build \ protobuf-compiler \ python3-empy这里特别注意python3-empy这个包Ubuntu 24.04 软件源里可能没有它或者版本是4.x用pip安装3.3.4版本更稳妥。4. PX4源码获取与编译从git clone到第一个固件生成环境准备就绪后就开始拉取PX4源码。这里有几个关键选择下载哪个分支、用哪个镜像、编译哪个目标机型。4.1 选分支main还是releasePX4的官方仓库地址是https://github.com/PX4/PX4-Autopilot.git。截至2025年PX4稳定版本已经到2.x但很多教程基于v1.15或v1.14。作为入门学习我强烈建议不要用main分支可能不稳定选一个release版本分支最省心。cd ~ git clone https://github.com/PX4/PX4-Autopilot.git --recursive cd PX4-Autopilot git checkout v1.15.4 git submodule update --init --recursive4.2 国内拉取慢的替代方案直连GitHub拉取PX4仓库包括所有子模块数据量达到数GB网络不好的话可能要拉好几个小时甚至失败。替代方案是用GitHub镜像站比如gitclone.com或者ghproxy。git clone https://gitclone.com/github.com/PX4/PX4-Autopilot.git --recursive不过镜像站的子模块同步不一定完整clone完成后一定要执行git submodule update --init --recursive确保子模块都拉取完整。如果没有完整拉取编译时会报TinyXML或uavcan之类找不到头文件的错误。4.3 首次编译 Pixhawk 固件PX4支持多种目标硬件入门学习建议编译Pixhawk 4FMUv5或Pixhawk 6XFMUv6X的固件。编译命令格是make px4_fmu-v5_default首次编译需要下载许多第三方依赖比如Firmware工具链、NuttX RTOS等所以时间会比较长在性能较好的机器上大概需要15-30分钟慢的机器可能需要一小时以上。如果要启用Ninja加速构建设置环境变量export PX4_USE_NINJA1建议把这行加到~/.bashrc里这样每次终端打开就自动生效。Ninja的并行度默认根据CPU核心数自动分配不用手动指定-j参数。4.4 针对24.04的编译配置调整如果在编译时遇到gcc: internal compiler error或者某些头文件报错如bits/cconfig.h找不到多半是GCC版本与某些旧代码不兼容。v1.15版本的PX4对GCC 13支持还可以但确实会遇到个别情况经验处理方式方式一切换到GCC 12Ubuntu 24.04仓库里有GCC 12可以安装并切换默认版本sudo apt install -y gcc-12 g-12 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 100 sudo update-alternatives --install /usr/bin/g g /usr/bin/g-12 100方式二换用Docker编译如果GCC切换后问题依旧考虑用PX4官方的Docker镜像。但如果是纯入门学习Docker会带来额外的容器内设备映射、图形界面等复杂度建议先尝试GCC版本切换。4.5 编译成功的标志编译结束后产出文件在build/px4_fmu-v5_default/目录下重点看px4_fmu-v5_default.px4可用于QGroundControl地面站刷写的固件文件px4_fmu-v5_default.bin原始二进制固件px4可执行的仿真程序如果编译了仿真目标如果这个固件文件生成了说明工具链基本没问题PX4核心编译已经通过。5. 跑通 Gazebo 仿真验证PX4安装成功的最快方式编译完固件只成功了一半真正能证明环境完整、可以开始飞控开发的是跑通仿真。PX4的仿真环境基于Gazebo在Ubuntu 24.04上配置Gazebo有些细节需要注意。5.1 安装GazeboHonu即Gazebo 11PX4 v1.15使用的仿真器主要是Gazebo Classic即Gazebo 11。Ubuntu 24.04默认软件源不再提供Gazebo Classic需要添加OSRF软件源sudo apt install -y lsb-release wget gnupg sudo 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 | sudo tee /etc/apt/sources.list.d/gazebo-stable.list sudo apt update sudo apt install -y gazebo11 libgazebo11-dev5.2 安装PX4仿真依赖进入PX4源码目录运行官方仿真依赖脚本cd ~/PX4-Autopilot bash ./Tools/setup/ubuntu.sh --sim这个脚本会安装PX4仿真所需的全部依赖包括Gazebo插件、MAVSDK等。执行时间会比较长过程中如果遇到pip报错就按前面说的加--break-system-packages或先激活虚拟环境。如果脚本执行失败或超时也可以手动安装Gazebo插件依赖sudo apt install -y \ libgazebo11-dev \ protobuf-compiler \ libeigen3-dev \ libopencv-dev \ libboost-all-dev5.3 运行PX4仿真并连接QGroundControl安装完成后启动Gazebo仿真cd ~/PX4-Autopilot make px4_sitl gazebo-classic这个命令会编译SITL软件在环仿真固件然后启动Gazebo界面显示一架四旋翼无人机模型同时终端会启动PX4的SITL进程输出pxh命令行提示符。在pxh命令行里输入commander takeoff可以测试起飞指令。正常情况无人机会起飞到一定高度悬停。再用QGroundControl地面站连接地面站会自动识别到UDP :14550端口上的PX4 SITL实例显示无人机状态和传感器数据。能在地面站上看到姿态信息和位置信息说明PX4环境彻底跑通了。5.4 24.04上运行Gazebo的性能问题在Ubuntu 24.04的虚拟机上跑Gazebo可能会遇到图形渲染特别卡的情况这很常见。解决方法有几个确保VMware或VirtualBox已经安装并启用3D加速将Gazebo环境变量设为使用较低画质export GAZEBO_MODEL_DATABASE_URI跳过在线模型下载关闭Gazebo的GUI用无界面模式gzserver运行仿真只保留PX4 SITL在跑我建议入门阶段直接把Gazebo窗口开起来看视觉效果对理解无人机姿态变化很有帮助卡一点也能接受。5.5 运行offboard模式或MAVSDK示例仿真跑通后可以尝试用MAVSDK-Python写一个简单的起飞脚本验证MAVSDK和PX4仿真之间的通信。pip install --break-system-packages mavsdk然后在另一个终端里运行一个简单Python脚本让无人机起飞import asyncio from mavsdk import System async def run(): drone System() await drone.connect(system_addressudp://:14540) print(Waiting for drone to connect...) async for state in drone.core.connection_state(): if state.is_connected: print(Drone discovered) break print(Waiting for drone to have a global position estimate...) async for health in drone.telemetry.health(): if health.is_global_position_ready and health.is_home_position_ready: print(Global position estimate ready) break print(Arming...) await drone.action.arm() print(Taking off...) await drone.action.takeoff() await asyncio.sleep(10) print(Landing...) await drone.action.land() asyncio.run(run())运行之前需要先在pxh命令行里把SITL设为offboard模式兼容。不过在入门阶段这个脚本不跑也没关系能在地面站看到数据已经算是成功了一大半。6. 环境验证清单跑完以下检查你的PXE开发环境才算真到位很多人装完环境以为能编译就算完成实际上编译通过、仿真能跑、代码能改这三者完全不是一回事。我建议按下面的清单逐项验证确保开发环境真正可用。[ ]git --version、python3 --version、cmake --version输出正常[ ]cd ~/PX4-Autopilot make px4_fmu-v5_default成功生成.px4固件文件[ ]make px4_sitl gazebo-classic能启动Gazebo窗口终端出现pxh提示符[ ] QGroundControl能通过UDP连接SITL地图上能看到无人机位置[ ] 在pxh中输入param set MAV_SYS_ID 2能正常设置参数不报错[ ]git status在PX4源码目录下不显示大量未提交的修改如果以上检查全部通过就可以开始后续的学习了比如阅读PX4模块源码、编写自定义飞行模式、添加传感器驱动等。如果某些检查失败不要急着重装系统。99%的问题出在依赖版本冲突或环境变量配置上按前面提到的排查方式逐一排除即可。记住环境搭建最忌讳的就是反复重装系统那不是解决问题只是把问题推迟到下一次。我自己的经验是环境搭建阶段遇到问题先检查三个地方第一Python相关包的版本第二CMake和编译器版本第三Git子模块是否完整。这三点占掉了PX4安装类问题的大半原因。7. 避坑总结我在Ubuntu 24.04上装PX4踩过的12个具体问题把这一路上的坑集中整理一下方便遇到问题时直接索引。7.1 依赖安装阶段的问题问题根因解决方案pip安装报externally-managed-environmentPEP 668pip命令加--break-system-packages或使用虚拟环境empy版本过高导致构建失败empy 4.x不兼容pip install empy3.3.4apt update卡死或404源文件格式不匹配检查/etc/apt/sources.list.d/ubuntu.sources是否配置正确gcc: internal compiler errorGCC 13兼容性问题切换到GCC 12submodule拉取超时网络问题使用镜像仓库后执行git submodule update --init --recursive7.2 编译阶段的问题问题根因解决方案编译过程中OOM内存不足增加交换空间或降低并行度framework/...头文件找不到子模块不完整git submodule update --init --recursivePX4-Autopilot/Tools/setup/ubuntu.sh执行到一半失败某个依赖安装失败检查报错依赖手动安装后重新执行脚本7.3 仿真阶段的问题问题根因解决方案Gazebo窗口黑屏GPU驱动或VM 3D加速不足开启虚拟机的3D加速物理机安装GPU驱动Gazebo模型只有地面没有无人机模型库加载异常检查~/.gazebo/models模型缓存或重新执行make px4_sitl gazebo-classicQGroundControl连不上SITLUDP端口不匹配确认QGC使用UDP端口14550或手动在pxh里连MAVLinkSITL启动报Missing gazebo model模型文件路径错误确认PX4_SITL_WORLD和PX4_SITL_MODEL环境变量正确7.4 一个容易忽略的问题磁盘空间PX4源码含子模块加上编译产物再加上Gazebo模型库总占用可能会超过20GB。如果磁盘空间不足编译会报各种奇怪的错误比如No space left on device。入门阶段最好预留至少30GB空间。检查方法df -h du -sh ~/PX4-Autopilot如果发现空间不足清理编译缓存make clean或者删除旧的编译目录build/需要时重新编译。8. 环境搭好之后下一步学什么环境搭好只是万里长征第一步。很多人装好环境、跑通仿真然后就开始迷茫接下来该干什么我的建议是按以下顺序继续推进第一学PX4源码结构。PX4的源码组织很清晰src/modules下是各个模块比如mc_pos_control是多旋翼位置控制、mc_att_control是姿态控制、navigator是导航逻辑。花点时间熟悉每个模块的职责和它们之间的消息通信机制uORB这是看懂PX4后续一切内容的基础。第二学uORB消息机制。PX4内部模块之间通过uORB发布/订阅消息通信。在msg/目录下可以看到所有消息定义比如vehicle_attitude.msg、vehicle_local_position.msg。理解了这个机制你才能写自己的模块并接入PX4系统。第三改一个简单模块试试。比如把一个现有模块的日志输出改一下重新编译烧写看看改动有没有生效。这个过程会逼你把编译、烧写、调试整个链路走通。第四接真机。买一块Pixhawk 6C或者类似的飞控板在QGroundControl上刷入自己编译的固件然后找一个安全的空旷场地试飞。真机上遇到的问题比如磁力计校准、电调校准、PID调参是仿真模拟不了的这才是飞控开发真正的魅力所在。我不建议一上来就折腾各种高级功能比如视觉避障、SLAM、集群控制。那些都是在基础链路非常熟练之后才能涉及的领域。先把改代码-编译-刷固件-验证这个闭环跑顺再谈别的。另外有条件的话强烈建议把~/.bashrc里加上以下几行减少很多重复工作export PX4_USE_NINJA1 source ~/px4_venv/bin/activate这样每次打开新终端都自动启用Ninja编译和Python虚拟环境不用每次都手敲一遍。环境搭建这个阶段折磨人的程度和后面上手飞控开发的爽快感成正比。别急着放弃也别急着跳过任何一步。把这篇里的步骤一步步走一遍该踩的坑踩完后面的路会顺很多。