本页是包开发基础的姊妹页面。前提是你已经掌握包开发的基础知识(Service Provider、
composer.json 结构等)。应对 Laravel 主版本升级
应对流程
1
更新 composer.json 的 require
向依赖范围中添加新版本。若要继续支持旧版本,用 新版本适配完成、结束旧版本支持时删除旧约束。
|| 并列。2
用新版本运行测试
在本地或 CI 环境使用新的 Laravel 版本运行测试。通过即可基本确认兼容性。未通过时需要针对变更或删除的 API 进行修改。
3
向 GitHub Actions 测试矩阵添加新版本
在 CI 测试矩阵中加入 Laravel 新版本,持续验证兼容性。详见测试矩阵配置示例。
4
发布新版本适配
将包含
composer.json 变更的新版本打标签并发布。用户只需 composer update 就能在新的 Laravel 版本上安装。参考官方包
对适配方式犹豫时,参考 Laravel 官方包的composer.json 最为稳妥。
这些包由 Laravel 团队维护,是最早适配新版本的实例,illuminate/* 依赖版本的写法也很有参考价值。
PHP 版本要求的更新
Laravel 升级有时会提高 PHP 最低要求。请一并在包的composer.json 中更新 PHP 要求。
积极使用新 PHP 特性时
若要使用 PHP 8.3 之后的特性(类型化常量、新的随机函数等),需要判断是否要提高最低要求。从 SemVer 角度看提高最低要求属于破坏性变更,因此建议在主版本升级时进行。结束旧版本支持的策略
一直维护旧版本从长远看会拉高维护成本。制定明确的支持策略并定期结束旧版本支持,是包健康运营的重要一步。结束支持的时机
常见做法是与 Laravel 支持期对齐。Laravel 为每个版本提供 18 个月 Bug 修复与 2 年安全修复。包也采用相同策略会让用户更易理解。在 README 中写明支持策略
为让用户对预期有正确的判断,请在README.md 中记载支持策略。
维护旧版本的成本
持续维护旧版本会产生以下成本。- 重复的 Bug 修复 — 需要在多个分支修复同一 Bug
- 分支代码增加 — 用条件分支处理各版本差异,复杂度上升
- 测试矩阵膨胀 — CI 运行时间变长
- 安全补丁更复杂 — 需要谨慎地向旧版本回移
早期适配的优势
在 Laravel 发布同时完成适配,用户可以立刻迁移到新版本。这是包信誉的重要信号。用开发版预先验证
Laravel 不发布 beta/RC,但可以通过dev-master 或 @dev 安装尚在开发中的下一版本。在主版本发布前预先跑通,就能做到零日适配。
@dev 约束安装。
minimum-stability 设为 dev 可以解析对开发版的依赖。
第一步只改 composer.json 就够了
在完成完全兼容性确认之前,仅仅更新composer.json 的依赖范围并发布,就能让用户安装到包。
追踪发布信息
以下是及时把握新版本发布信息的手段。测试矩阵配置示例
以下是 GitHub Actions 中对多种 Laravel 与 PHP 版本组合进行自动测试的工作流示例。fail-fast: false 的重要性
设置fail-fast: false 后,即便某个组合失败,其他组合的测试仍会继续。可以在一次 CI 中知道所有出问题的组合。
逐步更新测试矩阵
Laravel 新版本发布后加入矩阵,结束旧版本支持时再从矩阵移除。composer.json 示例
以下是支持多版本的composer.json 完整示例。
版本升级应对清单
Laravel 新版本发布前
Laravel 新版本发布前
- 用开发版(
dev-master/@dev)跑通功能 - 在官方 Upgrade Guide 中确认破坏性变更
- 在测试环境实现新版本适配
- 将新版本加入测试矩阵在 CI 中验证
发布后初期应对
发布后初期应对
- 在
composer.json的illuminate/*中加入新版本 - 按需更新 PHP 要求
-
require-dev中的orchestra/testbench也升级到对应版本 - 打新版本标签并同步到 Packagist
- 更新 README 中的版本兼容表
结束旧版本支持时
结束旧版本支持时
- 在 CHANGELOG/README 中明确写出停止支持
- 从
composer.json中移除旧版本约束 - 从测试矩阵中移除旧版本
- 清理旧版本相关的条件分支代码
相关页面
包开发基础
以 Service Provider 为核心讲解 Laravel 包的开发方法。
使用 Pest 进行进阶测试
讲解使用 Pest 的 Expectation API 与数据集来编写包测试的方法。