PHP 8.5 升级到生产环境怎样检查扩展兼容

PHP 8.5 升级到生产环境时，扩展兼容不能只看 php -v 是否变成 8.5。更可靠的判断是：目标机器上的 CLI、PHP-FPM、定时任务和队列进程分别加载了什么扩展，项目锁定依赖声明了什么平台要求，以及 PHP 8.5 迁移文档中的不兼容项是否覆盖了现有代码。

PHP 官方迁移指南明确提醒，8.5 的新特性和少量不兼容变化需要在切换生产版本前测试；官方发布页还列出了 URI 扩展、管道运算符等变化。下面给出一套适合发布前执行的检查顺序。

官方资料：https://www.php.net/manual/en/migration85.php

结论：先复制生产扩展清单，再用目标 PHP 8.5 运行时检查扩展是否加载，最后用 Composer 检查锁定依赖；三者都通过后，再用 FPM 和队列的灰度回归结果决定是否切换。

先把升级范围固定下来

先不要在生产机上直接替换二进制。为本次升级建立一张简短的基线表：旧 PHP 版本、目标 PHP 版本、SAPI 类型、配置文件位置、已加载扩展、Composer 锁文件版本，以及可执行的回滚方式。

按业务入口整理扩展兼容矩阵

不要把整台机器的扩展列表直接当作兼容结论。将扩展按业务入口分组，至少区分 Web、CLI、队列和定时任务。例如，pdo_mysql 负责数据库访问，mbstring 影响多字节字符串处理，intl 影响本地化，gd 或 imagick 影响图片处理，redis 可能由队列和缓存共同使用。

这段检查适合放在部署前或健康检查脚本中，但不要把“所有环境都必须安装同样的扩展”当作原则。可选图片扩展可以由功能开关决定；而数据库、队列、加密等核心入口缺失时，应直接阻止发布。

把 PHP 8.5 迁移变化映射到代码

PHP 8.5 的迁移指南包含新特性、向后不兼容变化和弃用项。发布前重点检查三类内容：旧语法是否被弃用、类型或警告是否改变、扩展接口是否依赖新的运行时行为。

• 反引号作为 shell_exec() 别名已被弃用，搜索旧代码并改用明确的函数调用。
• 非规范类型转换名称如 (integer)、(boolean) 被弃用，应改为短形式。
• 对 null 使用数组偏移或调用 array_key_exists() 会产生弃用提示，重点检查错误处理和输入归一化路径。
• __sleep() 与 __wakeup() 被软弃用，序列化对象的代码应评估 __serialize() 与 __unserialize()。

# 在候选 PHP 8.5 环境中记录版本与配置文件，不要只检查开发机。
php -v
php --ini

# 列出普通扩展和 Zend 模块，输出保存到本次发布记录中。
php -m

# 用错误报告捕获弃用提示；脚本路径替换为项目的无副作用启动检查。
php -d error_reporting=E_ALL -d display_errors=1 bin/compatibility-smoke.php

检查代码时要把“语言变更”和“扩展加载失败”分开记录。前者通常通过静态搜索和回归用例处理，后者要回到镜像构建、系统包、extension_dir 和对应 SAPI 的配置加载路径。

用真实运行时检查 Composer 平台依赖

Composer 的平台包包括 PHP 本身和 ext-* 扩展。仅在开发机运行 composer install，并不能证明生产 PHP 8.5 已满足锁定依赖。Composer 官方建议使用 check-platform-reqs 检查真实平台；该命令会忽略 config.platform 的伪装值。

# 只读取锁文件中的生产依赖，避免 dev 依赖掩盖生产环境结论。
composer check-platform-reqs --lock --no-dev

# 如果部署目录已安装依赖，也可以检查当前实际 vendor 状态。
composer check-platform-reqs --no-dev

# 失败时保留完整输出；不要用 --ignore-platform-reqs 把缺失扩展变成“通过”。

如果项目使用了 config.platform，它可以帮助依赖解析模拟目标版本，但不能替代候选 PHP 8.5 进程的真实检查。生产构建阶段应让 composer check-platform-reqs 成为失败即停止的门槛。

分别检查 CLI、FPM 和队列进程

同一台机器上，CLI 与 FPM 可能读取不同的 php.ini 或扫描目录；队列进程还可能长期不重启，继续运行旧版本的扩展。发布前应分别采集三类证据：启动版本、配置入口和关键模块。

# CLI 只代表当前命令行进程，不能代替 FPM 的检查。
php -r 'echo PHP_VERSION, PHP_EOL; echo php_ini_loaded_file(), PHP_EOL;'

# 让 FPM 在候选环境启动并查看启动日志；服务名按发行版调整。
sudo systemctl restart php8.5-fpm
sudo journalctl -u php8.5-fpm --since "10 minutes ago" --no-pager

# 重启队列消费者，确保长驻进程加载的是 PHP 8.5 与新扩展集合。
sudo systemctl restart app-worker.service

这里的重点不是重启命令本身，而是不要把 CLI 的 php -m 结果复制到发布单上就结束。FPM 的启动日志、队列消费者的进程版本和健康检查输出，应分别绑定到对应入口。

用灰度回归决定是否切换

扩展列表通过后，选择能覆盖扩展边界的最小业务集：一次数据库读写、一次缓存读写、一次字符处理、一次图片处理（如果项目使用）、一次加密签名、一次队列消费。记录请求状态、异常日志和关键业务结果，不要只看进程是否存活。

1. 先在与生产相同的 PHP 8.5 镜像中执行 Composer 平台检查。
2. 启动 FPM 与队列，确认它们使用目标版本和相同的必需扩展集合。
3. 将少量无状态 Web 流量导入灰度实例，观察启动错误、弃用提示、数据库和缓存异常。
4. 完成一轮队列消费和定时任务，确认长驻进程没有因旧扩展或旧配置继续运行。
5. 保留旧运行时和旧镜像，达到回滚条件时优先切回流量，而不是在故障中临时安装扩展。

发布前最后核对这六项

可以把下面清单作为 PHP 8.5 扩展兼容的最小发布记录：

1. 旧版本、目标版本和回滚镜像已登记。
2. CLI、FPM、队列的 php.ini 与扩展列表分别留档。
3. 必需扩展、可选扩展和观测扩展已按业务入口分类。
4. PHP 8.5 迁移指南中的不兼容项已映射到代码检索或回归用例。
5. composer check-platform-reqs --lock --no-dev 在目标运行时通过。
6. 灰度 Web、数据库、缓存、图片/加密和队列路径通过，且回滚条件明确。

这样检查的结果不是一句“PHP 8.5 兼容”或“不兼容”，而是一份能回答“哪个入口、哪个扩展、哪条业务路径已经确认”的发布证据。扩展兼容先解决运行时集合问题，再解决依赖和业务行为问题，生产切换会更可控。

相关问题

php -m 通过，为什么网站仍然提示缺少扩展？

最常见原因是 CLI 和 PHP-FPM 使用了不同的配置文件或扫描目录。应分别查看 FPM 启动日志和对应 SAPI 的配置，不要只复用 CLI 输出。

可以用 config.platform 代替 PHP 8.5 真机检查吗？

不可以。它主要服务于依赖解析的目标平台模拟；最终仍要在 PHP 8.5 的真实运行时执行 Composer 平台检查。

扩展版本号和 PHP 版本号必须完全一致吗？

不应按字符串相等判断。应以扩展是否能在目标 PHP 运行时加载、Composer 的 ext-* 要求是否满足，以及关键业务回归是否通过为准。