PHP 大版本升级前的那张清单:语法扫描、兼容性检查与运行时报错的三步盘点

一、现象:模板和插件只差一个版本,站点就白了

升级服务器上的 PHP 常常是件被动的事:操作系统生命周期结束、某个依赖库要求新版本、或者你想试试 JIT 带来的性能提升。真正让人措手不及的不是主程序装不上,而是升级完打开站点,首页一片白或者满屏 Deprecated 警告,后台登录之后点哪个菜单都跳出 notice,评论、搜索、缩略图这些功能零零散散坏掉一部分。

多数人第一反应是把 PHP 降回去。降级确实能让站点恢复,但版本很快还会再逼过来,而且降级过程中你已经把旧版本的扩展装来装去,环境变得说不清。更合理的路径是花两三个小时,把「哪些代码在新版本下不兼容、影响多大、能不能在小版本内跳过」这件事一次弄清楚,然后分阶段切过去。

这篇文章不讨论语法特性本身,而是给出一套可执行的盘点方法:怎样在不影响线上站点的前提下开一台并行环境、怎样用静态检查和运行时日志把问题分类、怎样区分「必须改代码」「改配置能过」「只能等插件作者」三类情况。

二、先确认升级对象:主版本、次版本与扩展版本

很多人说的「PHP 升级」其实是三件不同的事,混在一起讨论必然乱。第一件是主版本号变化,比如 7.4 到 8.0,废弃的语法和默认行为改动最多,是最需要盘点的;第二件是次版本变化,比如 8.1 到 8.2,主要是新增特性加上一部分废弃提示,风险中等;第三件是补丁版本和安全更新,几乎不该犹豫,直接打。

与之并列的还有扩展版本。PHP 官方扩展要跟着主程序走,但 PECL 上的第三方扩展(imagick、redis、swoole 之类)常有滞后,主程序已经到 8.4 而扩展还没有对应编译版本的情况并不少见。所以盘点清单的第一张表应该是「主程序版本 + 已加载扩展及其来源」。

php -v
php -m | sort
php --ini
dpkg -l | grep -E 'php[0-9.]*-(fpm|cli|mysql|curl|gd|mbstring|xml|redis|imagick)' | awk '{print $2, $3}'

把输出存成一份基线文件,升级后再跑一次做 diff,能立刻看出少了哪个扩展。丢了 mbstring 的表现是中文截断乱码,丢了 gd 的表现是缩略图生成失败、后台报 call to undefined function imagecreatetruecolor,这两种问题在站点上很显眼,而扩展列表里一行之差却不显眼。

三、搭一个并行环境,别在线上试

盘点最安全的做法是:新版本装在与线上并存的路径下,用另一组端口和另一套 socket,通过 hosts 或者临时域名访问,指过去的是同一份数据库副本。这样既能测到真实数据下的表现,也不会把线上搞坏。

apt install -y lsb-release ca-certificates apt-transport-https
curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg
echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/sury.list
apt update
apt install -y php8.3-fpm php8.3-cli php8.3-mysql php8.3-curl php8.3-mbstring php8.3-xml php8.3-gd php8.3-zip

装完检查两件事:旧的 php8.1-fpm 服务别被 apt 顺手停掉或改成默认;update-alternatives 里 php 指向哪个二进制,会影响命令行 cron 脚本的版本。FPM 的池配置文件在 /etc/php/8.3/fpm/pool.d/,默认叫 www.conf,监听 unix socket。并行环境建议单独建一个池,名字叫 oldtest.conf,socket 路径 /run/php/php8.3-fpm-oldtest.sock,避免和线上池抢同一个 socket。

[oldtest]
user = www-data
group = www-data
listen = /run/php/php8.3-fpm-oldtest.sock
listen.owner = www-data
pm = dynamic
pm.max_children = 6
pm.start_servers = 2
pm.max_requests = 500
catch_workers_output = yes
php_admin_value[error_log] = /var/log/php8.3-oldtest-error.log
php_admin_flag[log_errors] = on
php_admin_value[error_reporting] = E_ALL

关键在最后两行。测试环境必须把 error_reporting 开到 E_ALL 并且写进文件,否则你会以为「没有报错」,其实是 display_errors 关着、log_errors 关着,问题安静地发生。正式切换前再把它调回生产口径,这一步别忘了。

四、静态检查先行:用语法与兼容性扫描圈定范围

环境准备好之后,先不改代码,做一轮只读扫描。第一层是语法检查,语法错误会导致整个文件直接崩,最容易也最该先清掉。

find /var/www/site -name '*.php' -not -path '*/vendor/*' -print0 \
  | xargs -0 -P 4 -n 1 php8.3 -l 2>&1 \
  | grep -v 'No syntax errors'

-P 4 并行能明显加速,但错误输出会交错,所以先把结果写进文件再筛选更稳。第二层是兼容性扫描,PHP_CodeSniffer 的 PHPCompatibility 规则集能够按目标版本检查废弃函数、移除的常量、参数签名变化。

composer global require squizlabs/php_codesniffer
composer global require phpcompatibility/php-compatibility
export PATH=$PATH:$HOME/.config/composer/vendor/bin
phpcs -p /var/www/site --extensions=php --ignore=vendor \
  --standard=PHPCompatibility --runtime-set testVersion 8.3-

扫描结果通常三类:一是字符串中包含的 curl 调用被误报,忽略即可;二是自写代码里真实用到了废弃特性,比如动态属性、未声明变量自动创建、字符串转数字的隐式转换;三是第三方库里的问题,这类单独列出来,先判断库本身有没有新版本,再考虑是否临时加抑制注解。ignore 里务必排除 vendor 和缓存目录,否则输出会被几千条无关警告淹没。

五、动态检查:把每次运行时提示都收进文件

静态扫描看不到「运行时才会走到」的路径。所以第二层是动态:用改动最小的 nginx server 块把测试域名的请求转到新池,然后把整站跑一遍,包括首页、分类页、文章页、搜索结果、后台登录、发一篇文章、上传一张图、评论提交。

server {
    listen 443 ssl http2;
    server_name test.example.com;
    root /var/www/site;
    index index.php;
    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php8.3-fpm-oldtest.sock;
    }
    error_log /var/log/nginx/test-error.log warn;
}

跑完之后看日志里的关键词,按五类归组:Deprecated(还能跑,但下个版本会移除)、Warning、Notice 或 Undefined(隐性 bug,可能以前也存在)、Fatal(直接 500)、还有一类是 silent 的行为变化,不报错但结果不对,比如日期解析、浮点比较、字符串与数字比较的语义调整。前四类 grep 就能抓,第五类只能靠手工核对关键页面输出。

grep -oE '(Deprecated|Warning|Notice|Fatal error):[^\r]*' /var/log/php8.3-oldtest-error.log \
  | sed -E 's/ in \/var\/www\/site\// | /' | cut -c1-140 | sort | uniq -c | sort -rn | head -30

按条数排序后,通常 80% 的告警来自两三个文件。集中修这两三个文件,收益远大于逐个点开所有页面。

六、三类问题,三种处置方式

盘点完会得到一长串问题,处置时必须分类,否则很容易把时间花在收益最低的地方。

第一类是自写代码里可以立刻改的。典型是 string 函数签名收紧、返回类型声明、动态属性、以及被移除的函数。改法通常只有几行,改完在两套版本下都要跑一遍测试页。记住目标不是「消除告警」而是「保持行为一致」,有些废弃提示对应的行为变化(例如整型除法取整方向、字符串与数字比较)即使在旧版本上消除告警,新版本上也已经不同,这类必须单独写用例验证。

第二类是改配置就能过的。例如 display_errors 与错误级别、session 存储路径、上传大小限制、时区设置、以及新版本默认改变的 INI 项。这类不需要动代码,但一定要写进清单,因为切换那天你会以为「代码没改就不用管」,结果站点因为 session 目录权限或者 max_input_vars 变化出问题。

第三类只能等上游。插件或框架没有兼容版本时,硬改别人的代码会把后续升级路堵死。正确做法是先在隔离环境里标记为已知风险,评估功能是否还能用,如果某个次要功能坏掉,可以在切换当天先禁用该插件,把修复排到后续。千万不要为了一个日志插件去 fork 一份 vendor 目录,半年后你自己都说不清哪份是原版。

七、框架与 CMS 的版本配套关系

如果你跑的是现成的 CMS 或者框架,PHP 版本不能单独决定,得先看它对 PHP 的支持矩阵。老版本 CMS 往往在某个 PHP 大版本下直接不兼容,因为用到了已被移除的扩展或函数;反过来新版 CMS 也可能要求最低 PHP 版本。落地顺序是先升 CMS 到目标 PHP 支持的版本,再升 PHP。

框架场景还要注意依赖锁文件。composer.json 里如果用的是通配约束,升级 PHP 后 composer update 会顺手把几十个包一起更新,行为变化不可控。正确做法是锁定版本,只允许平台包(ext-*)的方案解析变化:

composer install --no-dev --optimize-autoloader
composer check-platform-reqs

check-platform-reqs 会直接告出哪个依赖要求的 PHP 版本与当前不符,比等运行时 Fatal 早得多。上线前再跑一次 composer install 确保 vendor 与锁文件完全一致,不要在生产机器上执行 update。

八、切换当天的执行顺序与回退方案

真正的切换应该在一个流量低谷的窗口完成,并且事先写好回退命令。顺序我一般这样走:先备份代码与数据库;再把 nginx 的 upstream socket 指向新池,但 keepalive 连接不会有感知;然后观察错误日志和 5xx 比例五分钟;最后逐个验证核心路径。

# 切换前留一份现场
cp /etc/nginx/sites-enabled/site.conf /root/backup/site.conf.$(date +%F-%H%M)
mysqldump --single-transaction zz1984 > /root/backup/db.$(date +%F).sql

# 切换:只改一行 socket 路径
sed -i 's#php8.1-fpm.sock#php8.3-fpm.sock#' /etc/nginx/sites-enabled/site.conf
nginx -t && systemctl reload nginx

回退就是把 sed 反过来做一次再 reload,不超过一分钟。因此切换前必须确认旧版本的 FPM 池还在运行、配置还留着,别在切换当天把旧版本 purge 掉。至少跑满一个完整发布周期(比如两周)再考虑卸载旧版本。

切换后要盯的四件事:5xx 比例、PHP 错误日志新增条目、页面加载时间有没有变差、以及 cron 任务是否正常。cron 那条最容易被忽略,因为命令行 php 版本和 FPM 版本是两套,update-alternatives 只改一种场景,定时脚本很可能还在用旧版本,或者被切到了新版本而脚本里有兼容问题。

九、小结:把升级当成一次盘点机会

升级 PHP 的痛感大多来自信息不足:不知道哪些代码会坏、不知道坏了影响谁、不知道能不能回退。用并行环境加静态扫描加运行时日志这三步,把不确定性压缩到一张可核对的表上,剩下的工作就是按优先级逐条处理。

顺带的好处是,扫描结果往往能暴露出几个早就存在但一直没被发现的 bug:未定义变量取值、字符串与数字比较的隐患、错误处理完全缺失的分支。这些问题在旧版本上只是恰好没出事,修完之后站点反而更稳。等到下次再升版本,你有基线文件、有清单、有测试脚本,两个小时的活会变成四十分钟。

Last modification:November 18th, 2026 at 07:27 pm

Leave a Comment