PHP 8.5 新语法发布后旧项目如何安排兼容性扫描

PHP 8.5 已经发布，旧项目不适合只把运行时镜像改成 8.5 就直接上线。更稳妥的做法是把兼容性扫描拆成四层：先固定目标版本和扩展，再读迁移手册筛高风险变化，接着用静态工具定位代码，最后在 PHP 8.5.x 环境跑回归和小流量灰度。

官方迁移手册：https://www.php.net/manual/en/migration85.php

扫描的目标不是证明“代码能启动”，而是找出 PHP 8.5 会改变旧项目行为的输入、语义和运行路径，并让每个问题都有负责人、验证方式和回滚动作。

先把“升级目标”固定成一份可复现基线

同样叫 PHP 8.5，CLI、FPM、队列消费者和定时任务可能并不使用同一套扩展。第一步先保存生产环境的 PHP 小版本、SAPI、扩展列表、composer.lock、环境变量名和启动命令。官方支持页显示 PHP 8.5 的安全支持周期较长，但这不等于项目依赖已经兼容。

# 在目标镜像中记录运行时信息，避免扫描环境与上线环境不一致
php -v
php -m
composer show --direct
composer check-platform-reqs
php -l public/index.php

这里的 check-platform-reqs 主要检查 Composer 包声明的 PHP 和扩展平台要求，不能替代语法与行为扫描。若线上有多个入口，应分别记录 FPM、CLI 和 worker 镜像，否则很容易只验证了网页请求，却漏掉队列任务。

迁移手册里哪些变化值得优先排查

PHP 官方迁移页把内容分成新特性、新函数、向后不兼容变化、弃用项等部分。旧项目第一轮不必追逐所有新增能力，先把会让原代码出现弃用告警、警告或不同结果的条目列成清单。

例如迁移页列出的弃用项，应该先在代码库中检索，再确认是否真的会被执行；只在注释或测试夹具里出现，不应和生产阻断问题放在同一个优先级。

静态扫描要分层，别把工具输出直接当结论

建议把扫描结果分成三类：解析失败属于阻断项；静态规则命中且能对应生产路径，属于上线前必须处理项；仅涉及未执行代码或开发脚本的弃用告警，则进入观察清单。一个最小的本地组合如下：

# 先做语法级检查，再用 PHPCompatibility 识别跨版本风险
find src tests -name '*.php' -print0 | xargs -0 -n1 php -l
vendor/bin/phpcs -p src --standard=PHPCompatibility \\
  --runtime-set testVersion 8.4-8.5
# 命令返回非零时，保留文件名、规则号和调用路径供复核

php -l 只能回答单文件能否解析；PHPCompatibility 的规则结果还需要结合项目的 PHPStan/Psalm、单元测试和代码所有者复核。不要为了让扫描变绿而一口气修改大量格式，先按风险分组提交，便于定位行为变化。

在 8.5.x 运行时做回归，再决定灰度范围

准备与生产一致的 8.5.x 镜像后，至少覆盖登录、支付回调、文件上传、队列消费、定时任务和 CLI 脚本。每条路径同时记录 HTTP 5xx、PHP 错误级别、队列重试、关键返回字段和 p95 延迟。扫描通过但运行时告警上涨，仍不能视为可发布。

 '12.50']);
assert($result === '12.50');

try {
    format_order_total(['amount' => null]);
} catch (\Throwable $e) {
    // 记录异常类型，确认 PHP 8.5 下仍由业务层接住
    error_log($e::class);
}

灰度时先放只读接口和低风险 worker，再逐步覆盖写入链路。若 5xx、弃用告警或任务失败率相对 PHP 8.4 基线明显上升，直接切回旧镜像，不要在流量升高时临时改代码。

兼容性扫描清单怎样落到发布单

发布单至少保留四项记录：目标镜像摘要、Composer lock、扫描报告链接和回滚镜像。每个命中项写清“是否进入生产路径、当前负责人、修复版本、验证命令”。对 PHP 8.5 的后续小版本，也要继续读取官方变更公告；小版本更新通常不是重新发起整套语言迁移，但安全和错误修复仍应在预发布环境跑一遍核心回归。

最后用下面的判断收口：没有阻断项，关键路径回归通过，8.5 与旧版本的错误和业务指标差异可解释，且回滚动作已演练，才适合扩大流量。否则继续留在灰度，不要用“新增语法很少”替代兼容性证据。

常见问题

PHP 8.5 兼容性扫描只跑 PHPCompatibility 可以吗？

不够。它擅长静态规则，仍需用目标版本运行时做语法检查、依赖安装和业务回归。

Composer 依赖都能安装就代表项目兼容吗？

不代表。依赖约束只说明安装条件满足，无法覆盖旧代码的弃用调用、类型变化和未覆盖的业务分支。

应该先升级 PHP 还是先改代码？

先建立 8.5.x 扫描环境并修复可确定的问题，再用灰度验证行为；不要直接替换生产运行时。