PX4源码下载与编译全攻略：从环境搭建到成功运行-编程阁

1. PX4开发环境搭建全指南

第一次接触PX4飞控系统时，我被它复杂的编译过程折腾得够呛。记得当时为了跑通第一个仿真，整整花了两天时间解决各种环境问题。现在回想起来，如果能有一套完整的指南，至少能节省80%的时间。下面我就把踩过的坑和解决方案都整理出来，让你能快速上手PX4开发。

PX4是一个开源的无人机飞行控制软件平台，支持从微型无人机到大型工业级无人机的各种应用场景。它最强大的地方在于提供了完整的仿真环境，你可以在电脑上测试代码，确认无误后再烧录到实际硬件。目前支持的主要开发环境是Ubuntu Linux，这也是我推荐使用的系统。

在开始之前，建议准备一台性能尚可的电脑，至少8GB内存，100GB可用存储空间。因为编译过程中会下载大量依赖和工具链，而且仿真运行也比较吃资源。我个人的开发环境是Ubuntu 20.04 LTS，这也是PX4官方推荐的操作系统版本。

2. 源码下载的三种方式及问题解决

2.1 标准克隆方法（适合大多数用户）

最直接的下载方式是使用git克隆官方仓库：

git clone https://github.com/PX4/Firmware.git --recursive

这个命令会下载主分支(master)的所有代码和子模块。但这里有个常见坑点：由于代码库较大，可能会遇到git缓存不足导致的下载中断。错误信息通常类似：

error: RPC failed; curl 56 GnuTLS recv error (-54) fatal: The remote end hung up unexpectedly

解决方法很简单，增大git的缓存大小：

git config --global http.postBuffer 2000000000

这个值设置为2GB，基本能满足需求。如果网络状况不好，可以考虑使用国内镜像源或者分时段下载。

2.2 指定版本下载（需要特定版本时）

如果你需要某个特定版本的PX4（比如为了兼容特定硬件），可以分步操作：

git clone https://github.com/PX4/Firmware.git cd Firmware git checkout v1.11.0 # 替换为你需要的版本号 git submodule update --init --recursive

这种方式比较灵活，但要注意子模块版本可能与主版本不兼容。我曾在v1.9.2版本上遇到过子模块冲突，最后是通过手动修改.gitmodules文件解决的。

2.3 官方脚本安装（最稳妥的方式）

对于新手，我强烈推荐使用PX4官方提供的安装脚本。这个方法虽然步骤稍多，但成功率最高：

wget https://raw.githubusercontent.com/PX4/Devguide/master/build_scripts/ubuntu_sim_nuttx.sh chmod +x ubuntu_sim_nuttx.sh source ubuntu_sim_nuttx.sh

这个脚本会自动安装所有依赖项，并配置好开发环境。完成后需要重启电脑使环境变量生效。我在三台不同配置的电脑上测试过这个方法，都能一次成功。

3. 依赖安装与Python环境配置

3.1 运行官方安装脚本

下载完源码后，第一件事就是安装依赖：

bash ./Tools/setup/ubuntu.sh

这个脚本会自动安装编译器、调试工具、仿真环境等所有必要组件。但Python依赖经常出问题，特别是国内网络环境下。典型错误如：

Could not find a version that satisfies the requirement argcomplete

3.2 解决Python依赖问题

最彻底的解决方案是修改脚本中的pip源：

打开Firmware/Tools/setup/ubuntu.sh
找到Python依赖安装部分
替换为以下内容：

echo "Installing PX4 Python3 dependencies" sudo python3 -m pip install --upgrade -i https://pypi.tuna.tsinghua.edu.cn/simple pip setuptools wheel sudo python3 -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r ${DIR}/requirements.txt

使用清华镜像源能显著提高下载速度。如果还是有问题，可以尝试先手动安装setuptools：

pip3 install --user setuptools==58.2.0

3.3 Python版本管理

Ubuntu系统默认Python版本经常引发问题。建议统一使用Python3：

sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 10

检查版本：

python --version # 应该显示Python 3.x pip --version # 应该对应Python3的pip

如果遇到权限问题，可以添加--user参数本地安装，或者使用virtualenv创建虚拟环境。

4. 编译与常见错误解决

4.1 首次编译测试

基础环境准备好后，可以尝试编译一个基础版本：

cd Firmware make px4_fmu-v4_default

这个命令会编译适用于Pixhawk 4硬件的固件。第一次编译会比较慢，可能需要30分钟到1小时，因为要构建整个工具链。

4.2 常见编译错误

问题1：隐式fallthrough警告被当作错误

error: this statement may fall through [-Werror=implicit-fallthrough=]

这是因为较新的GCC编译器更加严格。解决方法：

sudo apt-get update sudo apt-get install --only-upgrade ccache

更新ccache后重新编译即可。

问题2：protobuf缺失

ninja: error: 'PROTOBUF_PROTOC_EXECUTABLE-NOTFOUND', needed by 'Imu.pb.cc'

安装protobuf编译器：

sudo apt-get install protobuf-compiler

问题3：OpenCV版本冲突如果使用gazebo仿真，可能会遇到OpenCV版本问题。解决方法是在CMakeLists.txt中指定路径：

set(OpenCV_DIR "/usr/local/share/OpenCV")

4.3 硬件特定编译

不同硬件需要不同的编译目标，常见的有：

Pixhawk 4:make px4_fmu-v5_default
CUAV X7:make cuav_x7pro_default
仿真环境:make px4_sitl gazebo

编译成功后烧录到硬件：

make px4_fmu-v4_default upload

看到100%进度和"Rebooting"提示就表示成功了。

5. 仿真环境搭建与测试

5.1 Gazebo仿真编译

要运行软件在环仿真(SITL)：

make px4_sitl gazebo

第一次运行会下载Gazebo模型，可能需要较长时间。建议使用国内镜像：

echo "export SVGA_VGPU10=0" >> ~/.bashrc echo "export GAZEBO_MODEL_PATH=${GAZEBO_MODEL_PATH}:~/PX4/Firmware/Tools/sitl_gazebo/models" >> ~/.bashrc source ~/.bashrc

5.2 常见仿真问题

问题1：权限不足

[Err] [REST.cc:205] Error in REST request

解决方法：

sudo usermod -a -G dialout $USER sudo apt-get remove modemmanager

问题2：显示问题如果Gazebo界面显示异常，可以尝试：

export SVGA_VGPU10=0

问题3：模型加载失败如果Gazebo无法加载无人机模型，手动设置模型路径：

export GAZEBO_MODEL_PATH=$GAZEBO_MODEL_PATH:~/PX4/Firmware/Tools/sitl_gazebo/models

5.3 第一次飞行测试

成功启动仿真后，可以尝试基本指令：

commander takeoff # 起飞 commander land # 降落 commander arm # 解锁电机 commander disarm # 锁定电机

使用QGroundControl地面站可以获取更完整的控制界面和参数调整功能。

PX4源码下载与编译全攻略：从环境搭建到成功运行