3. PX4源码下载与版本管理：git clone与分支切换

好，咱们正式开始动手。这一节要解决的是「源码从哪来、怎么管版本」的问题。很多新手一上来就 git clone 完事，结果编译报错才发现分支不对——这种事我见过太多次了。

先检查一下机器上有没有装 Git。打开终端，敲下面这行：

git --version

如果返回类似 git version 2.25.1 的数字，说明环境就绪。要是提示「command not found」，那就得先装 Git。Ubuntu/Debian 用户：

sudo apt update
sudo apt install git -y

我个人习惯装完顺手配一下用户名和邮箱，不然 commit 时会弹警告：

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

小提示：邮箱最好跟你 GitHub 账号绑定的邮箱一致，后面提交 PR 或参与社区时会省很多麻烦。

PX4 官方源码托管在 GitHub 上。最直接的下载方式就是：

git clone https://github.com/PX4/PX4-Autopilot.git

这条命令会把整个仓库拉到当前目录下，生成一个叫 PX4-Autopilot 的文件夹。不过——你想想看，默认拉下来的是 main 分支，而 main 分支是持续开发中的版本，不一定稳定。

我建议你这么做：先指定一个稳定版本的分支来克隆，比如 v1.14.3：

git clone -b v1.14.3 https://github.com/PX4/PX4-Autopilot.git

这样拉下来的代码直接就是 v1.14.3 标签对应的状态，省得后面再切分支。

注意：国内网络环境有时 clone 很慢，甚至超时。我曾经在客户现场遇到过，等了半小时还没拉完。解决方案有两个：一是用代理，二是用国内镜像（比如 Gitee 上的同步仓库）。但镜像可能滞后几天，追求最新代码还是建议走官方源。

拉完代码后，进到目录里看看：

cd PX4-Autopilot
git branch -a

你会看到类似这样的输出：

* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/v1.12.3
  remotes/origin/v1.13.2
  remotes/origin/v1.14.3

PX4 的版本号遵循语义化版本规范：主版本.次版本.补丁。比如 v1.14.3，1 是主版本，14 是次版本，3 是补丁号。次版本号变化通常意味着功能更新，补丁号变化一般是 bug 修复。

我个人习惯用表格来记这些概念，清晰：

  核心原则：做产品开发时，永远基于稳定标签或长期支持分支。别直接拿 main 分支去编译烧录，除非你做好了随时踩坑的心理准备。

假设你之前 clone 的是默认的 main 分支，现在想切到 v1.14.3。有两种方式：

方式一：老派做法（git checkout）

git checkout v1.14.3

这会进入「分离头指针」状态——说白了就是当前工作区指向了一个标签，而不是一个分支。这时候如果你修改了代码并提交，这些提交不会属于任何分支，切换走就可能找不回来。

方式二：推荐做法（git switch）

git switch -c my_v1.14.3 v1.14.3

这条命令基于 v1.14.3 标签创建了一个叫 my_v1.14.3 的新分支，然后自动切过去。这样你后续的修改都在这个分支上，安全可控。

我的习惯：每次拿到新飞控板，我都会基于目标固件版本创建一个带项目名的分支，比如 px4_v1.14.3_cuav_v5。这样半年后回来看，一眼就知道当时用的是哪个版本、针对什么硬件。

PX4 依赖很多第三方库，这些库以 Git 子模块的形式挂在主仓库下。切换分支或标签后，子模块的版本可能不匹配。所以每次切换完，记得跑：

git submodule update --init --recursive

这条命令会拉取所有子模块并更新到主仓库记录的提交。我曾经有一次忘了跑这步，编译时报了一堆莫名其妙的头文件缺失错误，排查了半天才发现是子模块没更新。嗯，吃一堑长一智。

切换完分支、更新完子模块后，用下面几条命令确认状态：

git log --oneline -3          # 看最近3次提交
git status                    # 看工作区是否干净
git submodule status          # 看子模块版本

如果 git status 显示 nothing to commit, working tree clean，说明当前状态是干净的，可以放心进行下一步编译。

下面这张图把源码下载与版本管理的核心流程串起来了，你可以对照着操作：

这张图把整个流程分成了三步：先确认环境，再根据需求选择稳定标签或开发分支来克隆，最后切换并更新子模块。每一步都有对应的命令，照着走基本不会出错。

clone 到一半卡住：网络问题。可以加 --depth=1 参数只拉最新提交，减少数据量：git clone --depth=1 -b v1.14.3 https://github.com/PX4/PX4-Autopilot.git。不过这样会丢失历史记录，后续切分支可能受限。
切换标签后编译报错：八成是子模块没更新。先跑 git submodule update --init --recursive 试试。
本地修改了代码想切分支：要么先 git stash 暂存，要么 git commit 提交。强行切换会导致冲突。

曾经踩过的坑：有一次我在客户现场，用 git checkout v1.12.3 切到标签后直接改了代码，然后忘了这件事。过了两天切回 main 分支时，那些修改全丢了。后来我养成了习惯——只要基于标签工作，一定先 git switch -c 创建分支。

好了，源码下载和版本管理就讲到这里。代码在手，下一步就是编译了。记住：版本选对，事半功倍；版本选错，debug 到崩溃。