升级前的准备工作：评估当前构建环境、备份关键配置与Layer、阅读官方迁移指南

说实话，我见过太多人一上来就急着跑 bitbake，结果构建到一半报错，回头一看——旧的 build/conf 没备份，meta-layer 也没记录版本。嗯，这种坑我踩过不止一次。所以这一章，咱们老老实实把准备工作做扎实。

升级 Yocto 版本，说白了就是一次「系统迁移」。你想想看，迁移之前总得知道自己在哪、带了哪些行李、目的地有什么变化吧？

我个人的习惯是，先跑一遍 bitbake -s 把当前所有 recipe 的版本列出来，存个快照。这样升级后对比差异会非常直观。

核心检查清单：

主机操作系统与依赖库版本——Yocto 每个 LTS 版本对宿主机的要求都不一样。比如从 Dunfell 升到 Kirkstone，Python 3.8 变成了最低要求。
当前 Yocto 版本与分支——用 bitbake --version 确认，别凭记忆。
已启用的 Layer 列表——bitbake-layers show-layers 输出要保存。
构建目录（build/）的磁盘占用——我遇到过升级到一半磁盘满了的尴尬事。
BB_NUMBER_THREADS 和 PARALLEL_MAKE 设置——新版本可能对并行度有不同建议。

我曾经在一个项目里，团队用了三年没清理过 downloads/ 目录，里面堆了十几个版本的源码包。升级时 bitbake 自动重新下载，结果发现磁盘只剩 2GB……嗯，从那以后我每次升级前都会跑 du -sh * 看一眼。

备份这件事，说多了都是泪。我建议你至少保留三样东西：

备份对象	路径示例	为什么重要
构建配置	`build/conf/local.conf` `build/conf/bblayers.conf`	包含所有自定义变量、镜像选择、Layer 路径
自定义 Layer	`meta-custom/` 整个目录	你的 BSP、应用 recipe、补丁文件都在这里
模板与补丁	`meta-/recipes-/*.patch`	升级后可能不兼容，需要回退对比

我的备份小技巧：

用 git tag 打一个快照标签，比如 pre-upgrade-dunfell-2024。这样万一升级失败，git checkout 就能回到原点。比单纯复制目录更省空间，也更容易追溯。

另外，build/tmp/ 目录要不要备份？我个人建议：不用。它只是编译产物，升级后几乎肯定要全量重编。留着反而容易混淆。

这是最容易被跳过、也最不该跳过的一步。Yocto 每个大版本都会发布一份 Migration Guide，里面详细列出了：

我记得有一次从 Zeus 升到 Gatesgarth，官方指南里写了一句「python3 作为默认 Python 解释器」。我当时没在意，结果所有用 python 的 recipe 全部报错。后来老老实实对照指南，把 inherit python3native 加上了。

注意： 不要只看当前版本的 Migration Guide。如果你要跨多个版本升级（比如从 Thud 直接跳到 Kirkstone），需要把中间每个版本的指南都过一遍。累积变更可能比你想象的多得多。

怎么快速定位关键变更？我一般用这个流程：

下面这张图把升级前的准备工作串起来了。你可以把它当作检查清单来用：

你看，这三个步骤其实是环环相扣的。评估环境让你知道「我在哪」，备份让你有退路，读指南让你知道「要去哪」。跳过任何一步，后面都可能翻车。

额外提醒： 如果你用的是 Yocto LTS 版本（比如 Dunfell 3.1、Kirkstone 4.0），官方会提供更详细的迁移路径。非 LTS 版本之间的升级，破坏性变更可能更多，一定要仔细读 Release Notes。

好了，准备工作做到这里，你已经有了一个清晰的起点。下一步就是动手升级了——不过在那之前，我建议你把上面那张 SVG 图打印出来，贴在工位上。每次升级前对着过一遍，能省不少 debug 的时间。