PHP 8.5 升级生存指南：避免凌晨两点回滚的检查清单

定目标版本定义内部支持策略在动 CI 或 Composer 之前先回答一个问题在你的组织里这次升级完成意味着什么确定目标和截止日期PHP 分支有两年的活跃支持然后是两年的安全修复。官方支持表PHP 8.52025 年 11 月 20 日初始发布活跃支持至 2027 年 12 月 31 日安全支持至 2029 年 12 月 31 日支持窗口很宽裕——但你的内部截止日期通常由以下因素驱动合规要求托管镜像 / 基础容器框架支持窗口停留在仅安全修复阶段的成本。定义范围升级常常在这里无声失败写下什么包含、什么不包含包含运行时版本升级FPM/CLIComposer 依赖调整CI 矩阵更新生产环境上线策略升级后验证。不包含除非你明确加进去重构代码以使用 PHP 8.5 新特性与 PHP 8.5 无关的主要框架升级顺手改的重写。如果不定义范围升级会变成重写然后就会停滞。提前决定兼容性策略如果代码库需要在旧版 PHP 和 8.5 上同时运行一段时间用 CI 强制双版本兼容在生产环境切到 8.5 之前不要合并 8.5 专属语法比如|。如果做硬切换确保上线/回滚方案万无一失接受功能分支可能更早开始使用 8.5 专属语法。初始审计当前 PHP、扩展和依赖约束大多数PHP 升级bug 不是语言 bug而是环境不匹配。快照实际运行的运行时在生产环境运行这些命令不是你的笔记本php -v php -m php --ini php -i | head -n 50如果用 PHP-FPM还要捕获FPM pool 配置ini 覆盖传给 FPM 的环境变量opcache/JIT 设置这些在不同环境可能不同。创建可复用的平台快照脚本把这样一个脚本放到tools/php-platform-snapshot.php在每个环境开发/预发/生产运行。提交脚本本身不要让它成为口口相传的知识。?php declare(strict_types1); function ext_version(string $ext): ?string { $v phpversion($ext); return $v false ? null : $v; } $snapshot [ php_version PHP_VERSION, php_version_id PHP_VERSION_ID, sapi PHP_SAPI, os PHP_OS_FAMILY . . php_uname(r), ini_loaded php_ini_loaded_file(), ini_scanned php_ini_scanned_files(), extensions [], ]; $exts get_loaded_extensions(); sort($exts); foreach ($exts as $ext) { $snapshot[extensions][$ext] ext_version($ext); } echo json_encode($snapshot, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . PHP_EOL;这能给你两个有用的东西测试 8.5 时可以 diff 的什么变了记录快速发现预发能跑生产不能跑问题的方法——往往是生产多了一个扩展或 ini 不同。盘点 Composer 平台要求Composer 把你的 PHP 运行时和扩展当作平台包依赖可以 require 它们。有用的命令composer show --platform composer check-platform-reqscomposer show --platform列出 Composer 看到的平台包。composer check-platform-reqs验证你的真实服务器是否满足已安装包的 PHP/ext 要求它会故意忽略config.platform。这是在部署前发现生产缺 ext-intl最快的方法。构建 CI 矩阵在旧版 PHP 和 8.5 上运行测试把警告当信号CI 是让升级变得可预测的地方。规则在生产稳定运行 8.5 之前保留旧运行时在 CI 中即使你计划硬切换短暂的重叠期也能帮你避免我们在生产准备好之前合并了 8.5 专属代码。GitHub Actions 矩阵示例旧版 PHP PHP 8.5如果用 GitHub Actionsshivammathur/setup-php 支持直接指定8.5。name: CI on: push: pull_request: jobs: tests: runs-on: ubuntu-latest strategy: fail-fast: false matrix: php: [8.3, 8.5] # 调整为你的当前版本 目标版本 steps: - uses: actions/checkoutv4 - name: Setup PHP uses: shivammathur/setup-phpv2 with: php-version: ${{ matrix.php }} tools: composer:v2 coverage: none - name: Install dependencies run: composer install --no-interaction --prefer-dist - name: Run tests run: vendor/bin/phpunit区分错误、警告和弃用不要立刻把所有东西都当失败。先分类解析错误 / 致命错误阻止升级。行为变更通常需要测试 代码修复。弃用不一定阻止升级但它们预示未来会坏——而且可能很快淹没日志。PHPUnit 本身就区分 outcomesfailed/errored和 issueswarnings、risky tests 等。一个实用的升级策略即使存在弃用也让测试在 8.5 上通过但加一个单独的 CI job 来统计弃用数量并强制执行预算比如弃用不能超过 N 条。这通常比一夜之间打开任何弃用都失败更现实。弃用和行为变更像处理故障一样分类而非当重构PHP 8.5 新增了一批弃用特性和几个可能让人意外的不兼容变更。官方迁移指南对此有详细说明。一个有效的分类工作流暴露在 CI 和预发环境启用 E_ALL。分组按消息签名聚类相同文件/行/消息。排序按风险优先安全相关运行时正确性日志量 / 运维噪音未来破坏可能性。修复最小的安全变更。防止回归添加针对性测试或静态规则。到处都会冒出来的常见弃用这些是让团队说等等这以前居然允许的问题非规范的类型转换名称已弃用(boolean)、(integer)、(double)、(binary)→ 用(bool)、(int)、(float)、(string)。快速搜索grep 搜\(integer\)/\(boolean\)等应用 codemod或 Rector——后面会讲。case 语句用分号结尾已弃用用:。这常出现在一直能跑的老 switch 块里。用 null 作为数组偏移或在 array_key_exists 中已弃用PHP 建议用空字符串代替。这通常指向输入规范化 bug——修根本原因不只是修警告。递增非数字字符串已弃用用str_increment()代替。如果你有代码用$s做字母递增会看到这个。反引号操作符已弃用它是 shell_exec 的别名。即使你接受安全风险也不想让弃用警告风暴淹没生产日志。__sleep()和__wakeup()软弃用优先用__serialize()/__unserialize()或在过渡期同时支持两者。运维相关的弃用扩展、ini、空操作函数有些弃用是你不再需要这个了但仍可能让你措手不及curl_close()和curl_share_close()已弃用因为句柄会自动释放。imagedestroy()已弃用因为 GdImage 会自动释放。finfo_close()已弃用因为 finfo 对象会自动释放。MHASH_*常量已弃用。PDOuri:DSN scheme 因安全原因已弃用。如果你运维大型应用这些很重要因为它们可能日志爆炸噪音掩盖真正的错误或指示值得审查的安全敏感行为远程 URI 的 PDO DSN。值得尽早检查的不兼容变更来自官方列表class_alias()不能再用 array 或 callable 作为别名。对象到布尔的松散比较被统一为与(bool)$object行为一致。Trait 在父类之前绑定微妙的行为变更。某些 attribute 目标验证错误现在在编译期发生有选项可以延迟。你可能永远不会遇到这些。但如果遇到你希望它们在 CI 立刻失败——而不是在生产环境。Composer 策略lock 文件、平台要求和分阶段更新依赖管理是升级出问题的地方。理解 Composer 在检查什么Composer 把当前 PHP 版本建模为平台包php并据此检查你的依赖。所以你有两个相关的问题我的依赖图能在 PHP 8.5 上解析吗我的生产环境真的满足解析出的依赖图吗分阶段更新依赖不要一次性搞定一个实用的分阶段方法阶段 A不改变运行时解析依赖在当前 PHP 版本上更新依赖如果可能。目标减少同时出现的未知数。阶段 B假设在 PHP 8.5 上解析依赖在composer.json中用config.platform.php模拟 PHP 8.5 进行依赖解析临时的在分支上。然后可控地运行composer update。阶段 C在真实 PHP 8.5 运行时上安装在 CI/预发环境的真实 8.5 上运行完整测试套件。正确使用 Composer 的平台检查platform-check控制在 Composer 的 autoloader bootstrap 中生成platform_check.php。composer check-platform-reqs验证真实运行时是否匹配已安装包的要求。换句话说用config.platform来模拟和解析。用check-platform-reqs来确保生产实际兼容。升级期间会反复使用的安全更新命令常见模式# 保守地更新依赖 composer update --no-interaction --with-all-dependencies # 严格按 lock 文件安装 composer install --no-interaction --prefer-dist如果需要追查一个有问题的包显式更新它加依赖在 CI 的两个运行时上重新运行。避免把忽略平台要求当成解决方案。它能让你本地脱困但不是迁移策略。部署前添加可观测性这样你能证明升级是健康的如果不能度量就会争论。基线化健康的含义在部署 PHP 8.5 之前捕获错误率HTTP 5xx 未捕获异常慢请求率p95/p99内存使用趋势FPM worker队列延迟如果你跑 worker日志量尤其是警告/弃用。临时增加日志信号但不要让日志变成垃圾场在升级窗口期间加一个短期的升级视角是合理的在进程启动时记录 PHP 版本FPM/CLI worker给错误打上运行时标签旧版 vs 8.5按端点/worker 类型统计弃用数量。在 PHP 中你可以在前端控制器或框架 bootstrap里为预发环境添加一个最小的错误处理器set_error_handler(static function (int $severity, string $message, string $file, int $line): bool { if (!(error_reporting() $severity)) { return false; } // 示例把弃用/警告路由到专用 logger channel if ($severity E_DEPRECATED || $severity E_USER_DEPRECATED) { error_log([DEPRECATED] {$message} in {$file}:{$line}); return true; // 已处理 } return false; // 让正常处理器运行 });保持临时性。目标是上线期间的清晰度不是一个永久的自定义错误框架。确保绕过处理器的警告不会让你措手不及PHP 8.5 弃用了在用户输出处理器内部产生输出的行为并指出警告会绕过处理器以确保可见性。如果你做自定义输出缓冲的骚操作在预发环境用真实流量模式测试它们。上线策略金丝雀或蓝绿部署加上实际能用的回滚这是运维升级成败的关键。金丝雀基础最小可行的安全上线先把 PHP 8.5 部署到小比例的流量。对比错误率和延迟与基线。保持金丝雀足够长的时间以覆盖真实业务流程不只是健康检查。实现取决于你的技术栈负载均衡器后面的两个 FPM poolKubernetes deployment 加权重路由两个 ASG / 两个 service 加渐进流量切换。蓝绿部署适合大爆炸式组织如果你的组织偏好硬切换保持新旧环境都在线切换流量保持旧环境热备以便快速回滚。回滚计划必须包含依赖和缓存回滚不只是指回旧的 PHP 二进制。回滚现实性检查清单保留之前的容器镜像或包。保留之前的composer.lock制品。知道切换运行时时 opcache/APCu 或框架缓存是否需要清理。确保数据库迁移是向后兼容的或明确排除在升级范围外。如果回滚需要三个人和一份 wiki 页面在压力下它会失败。升级后检查清单先验证正确性再验证性能然后清理一旦 PHP 8.5 开始服务真实流量你的工作还没完。现在进入验证和稳定模式。即时检查第一小时扫描错误日志查找新的致命错误/异常。观察日志量是否突然增长通常是弃用。在生产主机上验证composer check-platform-reqs。用合成检查验证核心流程登录、结账、上传、定时任务端点。首日检查对比 p95/p99 延迟与基线。检查内存使用FPM worker RSS 增长worker 回收频率队列 worker 内存泄漏。验证后台任务worker 在新运行时上已重启没有卡住的队列没有静默失败。首周清理移除你为上线视角添加的临时额外日志。把高频弃用转成跟踪的工单并逐步消灭。再次收紧 CI提高弃用的标准确认稳定后从矩阵中移除旧 PHP 版本。关于 PHP 8.5 特性的快速兼容性说明不展开教程PHP 8.5 引入了新的语言和运行时特性如管道操作符、URI 扩展、clone-with 等。升级期间不需要采用它们。但你应该确保你的 linter/formatter 识别 PHP 8.5 语法确保 CI 在 PHP 8.5 上运行后再合并任何 8.5 专属语法把特性采用和运行时迁移分开范围控制。结论把升级当部署来对待就会顺利升级到 PHP 8.5 通常不是重写问题。是纪律问题定义范围审计真实平台运行 CI 矩阵系统地分类弃用和不兼容有意识地管理依赖上线前添加可观测性带着策略和回滚路径部署切换后验证和稳定。