将 Laravel 应用升级到 PHP 8.6:分步指南
PHP 8.6 于 2026 年 11 月 19 日正式发布,带来了“偏函数应用”(partial function application)、clamp() 函数、Time\Duration 类等新特性。本指南将介绍如何将 Laravel 应用从 8.5 版本升级至 8.6 版本,并采用一种能确保生产环境安全的方式进行操作;同时,文中还会涵盖你在升级过程中实际会遇到的弃用(deprecation)情况。
简言之:尽早进行测试,但推迟生产环境的升级。PHP 的小版本升级通常比较顺畅,但只要有一个软件包或扩展程序不支持新版本,就可能导致升级受阻。
第 0 步:首先检查兼容性
Laravel 框架本身
根据 Laravel 的支持列表,Laravel 13 支持 PHP 8.3 到 8.5 版本。通常,在 PHP 新版本正式发布后不久,Laravel 就会通过小版本更新(point release)增加对该 PHP 版本的支持。因此,请查看 Laravel 13.x 的发布说明,找到支持 PHP 8.6 的版本,并优先升级到该版本。如果你使用的是 Laravel 12 或更早版本,请务必先升级框架,再升级 PHP。
你的软件包
你可以通过 Composer 查看已安装的哪些软件包会阻碍升级到 PHP 8.6:
composer why-not php 8.6列表中提到的项目均为不包含 8.6 版本的 php 约束。请查看各项目的更新日志,确认是否有更新的版本发布。常见的问题来源通常是那些版本约束较为严格的软件包(例如 ^8.2 <8.6),或者是旧版本的测试工具。
关于托管环境
Forge、Laravel Cloud 以及大多数托管服务商,通常会在新版 PHP 正式发布(GA)后的几天到几周内提供支持。在计划将生产环境切换至新版本之前,请务必确认您的托管服务商是否已支持 PHP 8.6。
第一步:在本地安装 PHP 8.6
- Laravel Herd:在新版 PHP 可用后,在 Herd 的 PHP 设置中选择 PHP 8.6,然后切换你站点的 PHP 版本。
- Homebrew:执行 `brew install php@8.6`(或者在 8.6 成为默认版本后,执行
brew upgrade php)。 - Ubuntu:
ondrej/phpPPA 通常会很快发布新版本:
sudo apt install php8.6 php8.6-{cli,fpm,mbstring,xml,curl,mysql,zip,bcmath,intl,redis}- Sail / Docker: 在运行时更改 PHP 版本并重新生成。官方
php:8.6镜像不再附带pecl或内置 mbstring;
检查:
php -v
php -m # confirm the extensions your app needs are loadedphp-src 之外的扩展(如 Redis、Imagick、Swoole 等)需要针对 8.6 版本进行重新编译。由于在发布候选(RC)阶段进行了一次紧急安全修复,导致 PHP 8.6 的 ABI(应用程序二进制接口)发生了变更,因此基于早期 RC 版本编译的扩展必须重新编译。如果某个扩展尚未适配,它就会成为你升级过程中的阻碍。
第 2 步:更新 Composer 并运行测试
如果你的 composer.json 锁定了 PHP 版本,请放宽相应的 PHP 版本约束:
"require": {
"php": "^8.3"
}^8.3 已运行 8.6 版本。如果你使用 config.platform.php 来锁定依赖解析所用的版本,请务必等到生产环境也升级至 8.6 后,再将其相应地更改为 8.6。
composer update
php artisan test第 3 步:处理弃用项
PHP 8.6 引入了 31 项弃用(deprecation),这些弃用项均已在 8 月份的一次集中投票中获得通过。目前,这些变更不会导致您的应用无法运行:触发弃用时会产生一条 E_DEPRECATED 通知,但相关功能仍可正常使用。这些功能计划在 PHP 9 中被彻底移除。不过,这些通知会占用日志空间,可能导致测试套件运行失败,同时也为您升级至 PHP 9 明确了待办事项。以下是在 Laravel 代码库中最容易出现的弃用情况。
新增保留名称
这一点尤为重要,因为它会影响到目前仍可合法使用的名称:
| 名称 | 弃用 |
|---|---|
is | 作为函数、类、常量和其他标识符 |
let | 作为标识符 |
readonly | 作为函数名 |
namespace | 作为类常量名 |
_ | 作为常量名或者编译时别名 |
首先检查 is。Mockery 所依赖的 Hamcrest matcher 库(matcher library)中包含一个 is() 函数;此前,guzzlehttp/promises 库中曾出现过关于将 is 用作类名的预警。请勿修改 vendor 目录下的代码;应保持相关软件包处于最新版本。在您自己的代码中,请进行重命名:
// Before: deprecated in 8.6
function is(mixed $value): Matcher { /* ... */ }
class Status { const namespace = 'orders'; }
// After
function isEqualTo(mixed $value): Matcher { /* ... */ }
class Status { const NAMESPACE_NAME = 'orders'; }finally 中的 return
这是真正的行为性修复。在 finally 块中使用 return,会静默地吞掉 try 块中抛出的任何异常:
// Before: the exception is lost, the function returns null
function charge(Order $order) {
try {
return $this->gateway->charge($order);
} finally {
Log::info('Charge attempted');
return null; // deprecated in 8.6
}
}
// After: finally only cleans up
function charge(Order $order) {
try {
return $this->gateway->charge($order);
} finally {
Log::info('Charge attempted');
}
}如果发现了异常,请检查被吞掉的异常是否掩盖了真正的故障。
类型检查别名
| 弃用 | 替换 |
|---|---|
is_integer(), is_long() | is_int() |
is_double() | is_float() |
doubleval() | floatval() |
“查找并替换”一类的任务,完全可以通过 Rector 实现自动化。
其他值得通过搜索(grep)查找的内容:
strcoll()和SORT_LOCALE_STRING:请改用intl扩展中的Collator。spl_object_hash():请改用spl_object_id()。SplFileObject的 CSV 相关方法:建议考虑使用league/csv库。- 当
$allow_string参数为false时,在is_a()或is_subclass_of()中传入字符串。 - 在
array_walk()和http_build_query()等函数中,传入对象而非预期的数组。 - 最终并未被弃用的特性:
list()语法得以保留(投票结果为 23 票对 23 票,平局),_()(作为gettext的别名)也同样保留了下来。此外,将in、out和inout设为保留关键字的提议也未获通过。
如何查找这些内容
- 可以将相关记录定向到独立的日志文件中。在
.env文件中设置LOG_DEPRECATIONS_CHANNEL=deprecations,并在config/logging.php中添加一个deprecations通道(配置为按天轮转的文件即可)。 - 在
phpunit.xml中进行配置,使得遇到这些弃用项时测试失败:
<phpunit failOnDeprecation="true" displayDetailsOnTestsThatTriggerDeprecations="true">- 搜索(grep)自己的代码:
grep -rnE "\b(is_integer|is_long|is_double|doubleval|strcoll|spl_object_hash)\(" app/ config/ database/ routes/
grep -rnE "function (is|let|readonly)\(" app/- 运行已针对 PHP 8.6 进行配置的 PHPStan 或 Larastan;相比
grep,它们能更可靠地检测出finally块中的return语句。vendor/目录下的提示(Notices)无需你亲自修复:请更新相关软件包或查看其问题追踪系统(issue tracker),并将重点放在 `app/`、`config/`、`database/` 和 `routes/` 目录上。
第 4 步:在 CI 中加入 PHP 8.6
在生产环境完成迁移之前,请同时运行这两个版本。以 GitHub Actions 为例:
strategy:
matrix:
php: ['8.5', '8.6']
steps:
- uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php }}
第 5 步:部署至生产环境
- 先在预发布(Staging)环境进行部署。将预发布环境切换至 PHP 8.6,完成部署后,务必测试各项关键业务流程,例如:登录、结账、队列处理以及计划任务。
- 重启长时间运行的进程。队列工作进程(Queue workers)、Horizon、Octane 和 Reverb 等进程会将旧的 PHP 二进制文件保留在内存中,因此需要重启。
- 在上线后的第一天密切关注日志,重点查看弃用警告(deprecations)以及与扩展(extensions)相关的错误。
- 确保留有回滚方案。如果使用 Forge,只需点击一下即可将站点切回 PHP 8.5 版本;在开始操作前,请务必确认您所使用的托管平台是否具备类似的回滚机制。
故障排除
| 问题 | 修复 |
|---|---|
composer update PHP 约束失败 | 某个软件包尚不支持 8.6 版本。请检查是否有更新的版本发布。--ignore-platform-req=php 仅限本地测试使用,切勿用于生产环境部署。 |
| 切换后出现“Class not found"或致命错误 | 8.6 版本中缺少某个扩展。请对比不同版本下 php -m 的输出结果。 |
| 队列作业的表现与旧版本一致。 | 工作进程未重启:请执行 php artisan queue:restart,或重启 Horizon / Supervisor。 |
| 切换后的陈旧代码 | 重启 PHP-FPM 以清除 OPcache。 |
| 日志中充斥着弃用警告 | 在修复这些问题期间,将它们移至单独的频道,而不是直接将其静音。 |
常见问题
Laravel 13 支持 PHP 8.6 吗?
Laravel 13 发布时支持 PHP 8.3 到 8.5 版本。对 PHP 8.6 的支持通常会在 PHP 正式发布 (GA) 后,通过 Laravel 13.x 的小版本更新加入。因此,请先更新 Laravel,并查看相应的发布说明。
PHP 8.6 中的弃用项 (deprecations) 会导致我的应用无法运行吗?
不会。在 PHP 8.6 中,弃用项仅会触发提示 (notices)。这些功能将在 PHP 9 中被彻底移除,因此建议趁现在尽早修复,以降低后续维护成本。
PHP 8.6 中哪项弃用对 Laravel 应用影响最大?
主要是关于“新保留名称”(newly reserved names) 的变更,这通常会通过 Hamcrest 等依赖项产生影响。请确保 Mockery 及其他测试相关的软件包保持在最新版本。
总结
请检查 Laravel 框架、各类软件包以及托管环境;在本地安装 PHP 8.6;运行测试(确保弃用提示可见)并修复代码中的相关问题;将 PHP 8.6 加入到持续集成 (CI) 流程中;随后在预发布环境 (staging) 进行测试,最后部署到生产环境。对于大多数 Laravel 应用而言,这通常只需一个下午的工作量。
你计划何时将生产环境迁移至 PHP 8.6?欢迎在评论区告诉我。