Laravel 每年 2〜3 月发布主版本。对包开发者来说，尽快完成对新版本的适配既是对生态的贡献，也是提升自身包信誉的重要活动。
本页是包开发基础 的姊妹页面。前提是你已经掌握包开发的基础知识（Service Provider、composer.json 结构等）。 应对 Laravel 主版本升级 应对流程
更新 composer.json 的 require
向依赖范围中添加新版本。若要继续支持旧版本，用 || 并列。 "require" : { "php" : "^8.2" , "illuminate/support" : "^12.0||^13.0" }
新版本适配完成、结束旧版本支持时删除旧约束。 "require" : { "php" : "^8.3" , "illuminate/support" : "^13.0||^14.0" }
依赖 illuminate/support 而非整个 illuminate/framework，可以保持依赖树精简。
用新版本运行测试
在本地或 CI 环境使用新的 Laravel 版本运行测试。 composer update vendor/bin/pest
通过即可基本确认兼容性。未通过时需要针对变更或删除的 API 进行修改。
向 GitHub Actions 测试矩阵添加新版本
在 CI 测试矩阵中加入 Laravel 新版本，持续验证兼容性。详见测试矩阵配置示例 。
发布新版本适配
将包含 composer.json 变更的新版本打标签并发布。用户只需 composer update 就能在新的 Laravel 版本上安装。
参考官方包 对适配方式犹豫时，参考 Laravel 官方包的 composer.json 最为稳妥。
这些包由 Laravel 团队维护，是最早适配新版本的实例，illuminate/* 依赖版本的写法也很有参考价值。
PHP 版本要求的更新 Laravel 升级有时会提高 PHP 最低要求。请一并在包的 composer.json 中更新 PHP 要求。
Laravel 最低 PHP 版本 Laravel 11 PHP 8.2 Laravel 12 PHP 8.2 Laravel 13 PHP 8.3 Laravel 14 PHP 8.4
"require" : { "php" : "^8.2" , "illuminate/support" : "^11.0||^12.0||^13.0" }
积极使用新 PHP 特性时 若要使用 PHP 8.3 之后的特性（类型化常量、新的随机函数等），需要判断是否要提高最低要求。从 SemVer 角度看提高最低要求属于破坏性变更，因此建议在主版本升级时进行。
"require" : { "php" : "^8.3" , "illuminate/support" : "^12.0||^13.0" }
提高 PHP 最低要求后，使用旧 PHP 的用户就无法升级你的包。请务必在 README 与 CHANGELOG 中明确注明并事先通知。
结束旧版本支持的策略 一直维护旧版本从长远看会拉高维护成本。制定明确的支持策略并定期结束旧版本支持，是包健康运营的重要一步。
结束支持的时机 常见做法是与 Laravel 支持期对齐 。Laravel 为每个版本提供 18 个月 Bug 修复与 2 年安全修复。包也采用相同策略会让用户更易理解。
判断标准 说明 Laravel 官方支持结束 与对应 Laravel 版本停止支持同步 使用情况 Packagist 下载统计显示旧版本用户变少时 增加功能的障碍 旧版本适配让新功能实现变得复杂时
在 README 中写明支持策略 为让用户对预期有正确的判断，请在 README.md 中记载支持策略。
## Version Compatibility | Package | Laravel | PHP | |---------|---------|------| | 3.x | 13.x | ^8.2 | | 2.x | 11.x, 12.x | ^8.2 | | 1.x | 10.x | ^8.1 | Only the latest major version receives new features. Security fixes are backported to the previous major version for 12 months.
维护旧版本的成本 持续维护旧版本会产生以下成本。
重复的 Bug 修复 — 需要在多个分支修复同一 Bug分支代码增加 — 用条件分支处理各版本差异，复杂度上升测试矩阵膨胀 — CI 运行时间变长安全补丁更复杂 — 需要谨慎地向旧版本回移
在整个生态持续升级的背景下，适时结束旧版本支持也能促使用户迁移到最新环境。
早期适配的优势 在 Laravel 发布同时完成适配，用户可以立刻迁移到新版本。这是包信誉的重要信号。
用开发版预先验证 Laravel 不发布 beta/RC，但可以通过 dev-master 或 @dev 安装尚在开发中的下一版本。在主版本发布前预先跑通，就能做到零日适配。
# 用 dev-master 安装下一版本 composer require laravel/framework:dev-master --no-update composer update vendor/bin/pest
也可以通过 @dev 约束安装。
composer require laravel/framework:^14.0@dev --no-update composer update vendor/bin/pest
将 minimum-stability 设为 dev 可以解析对开发版的依赖。
{ "minimum-stability" : "dev" , "prefer-stable" : true }
指定 prefer-stable: true 后，若存在稳定版会优先使用稳定版。既能用开发版测试，又能保证正式发布时自动切回稳定版。
第一步只改 composer.json 就够了 在完成完全兼容性确认之前，仅仅更新 composer.json 的依赖范围并发布，就能让用户安装到包。
"illuminate/support" : "^12.0||^13.0"
小问题可以在发布后通过 PATCH 版本修复。与其等完美适配，不如优先让包可以被安装。
追踪发布信息 以下是及时把握新版本发布信息的手段。
信息源 内容 GitHub Watch 功能 通过仓库「Watch → Custom → Releases」接收邮件通知。除 framework 外，也可以订阅其他主要包 Laravel 官方博客 主版本发布公告与新特性介绍 Laravel 官方文档 Upgrade Guide 破坏性变更清单 laravel/framework 提交日志 想抢先了解下一个版本时可直接看提交日志
测试矩阵配置示例 以下是 GitHub Actions 中对多种 Laravel 与 PHP 版本组合进行自动测试的工作流示例。
name : Tests on : [ push , pull_request ] jobs : test : runs-on : ubuntu-latest strategy : fail-fast : false matrix : php : [ 8.2 , 8.3 , 8.4 ] laravel : [ "^12.0" , "^13.0" ] include : - laravel : "^13.0" testbench : "^10.0" - laravel : "^12.0" testbench : "^9.0" name : PHP ${{ matrix.php }} - Laravel ${{ matrix.laravel }} steps : - uses : actions/checkout@v4 - name : Setup PHP uses : shivammathur/setup-php@v2 with : php-version : ${{ matrix.php }} extensions : dom, curl, libxml, mbstring, zip coverage : none - name : Install dependencies run : | composer require "laravel/framework:${{ matrix.laravel }}" \ "orchestra/testbench:${{ matrix.testbench }}" \ --no-interaction --no-update composer update --prefer-dist --no-interaction - name : Run tests run : vendor/bin/pest
fail-fast: false 的重要性 设置 fail-fast: false 后，即便某个组合失败，其他组合的测试仍会继续。可以在一次 CI 中知道所有出问题的组合。
逐步更新测试矩阵 Laravel 新版本发布后加入矩阵，结束旧版本支持时再从矩阵移除。
# 待 Laravel 14 发布后添加 matrix : laravel : [ "^13.0" , "^14.0" ] include : - laravel : "^14.0" testbench : "^11.0" - laravel : "^13.0" testbench : "^10.0"
composer.json 示例 以下是支持多版本的 composer.json 完整示例。
{ "name" : "acme/courier" , "description" : "A Laravel courier package" , "type" : "library" , "license" : "MIT" , "require" : { "php" : "^8.2" , "illuminate/support" : "^12.0||^13.0" }, "require-dev" : { "orchestra/testbench" : "^9.0||^10.0" , "pestphp/pest" : "^3.0" , "pestphp/pest-plugin-laravel" : "^3.0" }, "autoload" : { "psr-4" : { "Acme \\ Courier \\ " : "src/" } }, "autoload-dev" : { "psr-4" : { "Acme \\ Courier \\ Tests \\ " : "tests/" } }, "extra" : { "laravel" : { "providers" : [ "Acme \\ Courier \\ CourierServiceProvider" ] } }, "minimum-stability" : "stable" , "prefer-stable" : true }
版本升级应对清单 相关页面
包开发基础 以 Service Provider 为核心讲解 Laravel 包的开发方法。
使用 Pest 进行进阶测试 讲解使用 Pest 的 Expectation API 与数据集来编写包测试的方法。
