将生产环境平台从 Symfony 5.4 迁移到 Symfony 8

将生产环境平台从 Symfony 5.4 迁移到 Symfony 8

背景

MasMusculo/MMfit 是一个基于 Symfony 构建的健身房管理平台，被真实健身房每天用于管理会员、预约和账单。该平台运行在 Symfony 5.4 上，这一版本即将结束官方支持，代码库也积累了多年典型的历史遗留问题——产品的发展速度超过了其工具链的更新速度。

作为唯一的开发者，在平台处于生产环境、每天都在使用的情况下，于这样一个代码库上跨越四个主版本（5.4 → 6 → 7 → 8），与迁移一个经过充分测试的小型副项目完全是两个层级的问题。

跳版本带来的问题

面对遗留代码库，很容易产生直接从 5.4 跳到 8、一次性解决的冲动。但实践中这几乎总会带来麻烦：

• 每个 Symfony 主版本都会移除此前标记为废弃的 API。跳过某个版本，就会错过本可以提前告诉你该修复什么的废弃警告，直到它变成真正的破坏性问题。
• 第三方 bundle 很少能支持比其目标版本超前一到两个主版本以上，大跨度升级会迫使你一次性替换多个 bundle，而不是逐个处理。
• 一旦跨四个版本升级后出了问题，根本无法判断究竟是哪个版本引入了回归。

策略：每次只升一个主版本

真正奏效的方法刻意选择了"无聊"的做法：

1. 只升级到下一个主版本，其余保持不变。
2. 在本地和预发布环境运行应用，修复 Symfony 自身报告的每一个废弃警告，然后才继续下一步。
3. 在每次部署前，运行现有的回归测试，并对关键流程（注册、预约、支付）进行人工复测。
4. 将这一次版本升级部署到生产环境，观察日志和错误跟踪几天，再开始下一个版本的升级。

这比一次性大跳跃要慢，但每一步都足够小，便于理解，也便于在出问题时回滚，整个过程中平台也从未因此下线。

经验教训

• 废弃警告是一份待办清单，而不是噪音。 把每一条警告都当作下次升级前必须修复的事项，让原本充满风险的迁移变成了一份可预测的检查清单。
• 测试覆盖率低的遗留代码需要人工兜底。 在还没有自动化测试覆盖的地方，一份针对平台关键路径的简短人工检查清单，发现了本会影响真实健身房的问题。
• 独自一人完成这件事，既是技术问题，也是日程安排问题。 把四次升级分散在一段时间内完成，而不是集中打包处理，使每次改动都便于审查，也让平台在整个过程中保持稳定。

最终结果：MasMusculo/MMfit 如今运行在 Symfony 8 上，整个迁移过程零停机，且每天使用该平台的健身房未报告任何功能回归。