解决git --recursive克隆失败：分步策略与镜像源优化

1. 为什么你的 git clone --recursive 总是失败？

相信很多朋友在克隆一些大型开源项目，比如无人机领域的PX4固件、或者一些深度学习框架时，都遇到过这个让人头疼的问题。你满怀期待地输入了官方文档里给的 git clone --recursive https://github.com/xxx/xxx.git 命令，看着进度条一点点前进，心里正盘算着待会儿怎么编译。突然，命令行窗口就卡住了，然后弹出一行刺眼的红色错误：克隆 ‘https://github.com/xxx/xxx.git’ 到子模组路径失败。那一刻，是不是感觉血压都上来了？

更让人崩溃的是，这个递归克隆的过程是“一荣俱荣，一损俱损”。只要有一个子模块（也就是项目里嵌套的另一个小项目）因为网络波动下载失败，整个克隆过程就会中断。你之前已经下载好的几十上百兆的主项目代码，也跟着一起作废了。常见的做法是删掉整个文件夹，从头再来，然后祈祷下一次网络能争点气。这种“开盲盒”式的体验，我经历过太多次了，尤其是在国内访问GitHub不太稳定的时候。

其实，这个问题的根源并不复杂，主要就是网络连接的不稳定性。--recursive 参数的本意是帮你一次性搞定所有事情，自动初始化并更新项目里所有的子模块。但它就像一支纪律严明的军队，要求所有士兵（子模块）必须同步到达。任何一个掉队，整个行动就宣告失败。对于像PX4-Autopilot这样的项目，它包含了数十个甚至上百个子模块，分别指向GitHub上不同的仓库，要想一次性全部成功下载，对网络环境的要求就非常高了。理解了这个本质，我们就能放弃“毕其功于一役”的想法，转而采用更灵活、更抗干扰的分步策略和镜像优化方案，这正是本文要带你彻底解决的问题。

2. 核心策略：化整为零，分而治之

面对一个复杂的难题，最高明的策略往往不是硬碰硬，而是把它拆解成一个个可以独立解决的小问题。对于递归克隆失败，我们的核心思想就是 “化整为零，分步击破”。放弃一次性克隆所有内容的幻想，把“克隆主仓库”和“初始化子模块”这两个步骤拆分开来。这样，即使子模块的下载过程出现波折，我们宝贵的、已经下载好的主项目代码也不会受到牵连，无需重头再来。

这个策略的第一步，就是先拿到项目的“骨架”。我们使用不带 --recursive 参数的 git clone 命令，只克隆主仓库的内容。以PX4固件为例，官方命令是 git clone https://github.com/PX4/PX4-Autopilot.git --recursive。我们现在把它拆开，先执行：

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

这条命令运行完后，你会得到一个 PX4-Au