编程

将 Laravel 应用升级到 PHP 8.6:分步指南

11 2026-11-20 23:31:00

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/php PPA 通常会很快发布新版本:
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 loaded

php-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 扩展中的 Collat​​or。
  • 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 设为保留关键字的提议也未获通过。

如何查找这些内容

  1. 可以将相关记录定向到独立的日志文件中。在 .env 文件中设置 LOG_DEPRECATIONS_CHANNEL=deprecations,并在 config/logging.php 中添加一个 deprecations 通道(配置为按天轮转的文件即可)。
  2. 在 phpunit.xml 中进行配置,使得遇到这些弃用项时测试失败:
<phpunit failOnDeprecation="true" displayDetailsOnTestsThatTriggerDeprecations="true">
  1. 搜索(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/
  1. 运行已针对 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 步:部署至生产环境

  1. 先在预发布(Staging)环境进行部署。将预发布环境切换至 PHP 8.6,完成部署后,务必测试各项关键业务流程,例如:登录、结账、队列处理以及计划任务。
  2. 重启长时间运行的进程。队列工作进程(Queue workers)、Horizo​​n、Octane 和 Reverb 等进程会将旧的 PHP 二进制文件保留在内存中,因此需要重启。
  3. 在上线后的第一天密切关注日志,重点查看弃用警告(deprecations)以及与扩展(extensions)相关的错误。
  4. 确保留有回滚方案。如果使用 Forge,只需点击一下即可将站点切回 PHP 8.5 版本;在开始操作前,请务必确认您所使用的托管平台是否具备类似的回滚机制。

故障排除

问题修复
composer update PHP 约束失败某个软件包尚不支持 8.6 版本。请检查是否有更新的版本发布。--ignore-platform-req=php 仅限本地测试使用,切勿用于生产环境部署。
切换后出现“Class not found"或致命错误8.6 版本中缺少某个扩展。请对比不同版本下 php -m 的输出结果。
队列作业的表现与旧版本一致。工作进程未重启:请执行 php artisan queue:restart,或重启 Horizo​​n / 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?欢迎在评论区告诉我。

 

下一篇