本文目录导读：
** PHP 并行运行新旧版本代码：平滑迁移的5种实战策略与避坑指南
目录导读
- 为什么需要"新旧并行"？—— 遗留系统升级的痛点
- 基于 FastCGI 的多版本 PHP-FPM 隔离
- Nginx 层基于 URL/目录的灰度路由
- 代码层面的 "Feature Flag" 特性开关
- 消息队列异步解耦新旧业务
- 容器化（Docker）端口映射并行
- 高频问答（Q&A）—— 解决你的核心疑虑
在面临 PHP 版本升级（如 PHP 5.6 升 7.4 或 8.2）或引入新框架时，最危险的莫过于“一刀切”切换，一旦新代码存在隐藏的兼容性问题，全站瞬间 502 将导致严重业务损失。“并行运行”并非指同一进程内多线程（PHP 默认不支持），而是指在架构层面让新旧两套代码同时对外提供服务，通过流量控制逐步切换。
以下综合 Laravel 官方升级文档、WordPress 社区迁移经验及 Swoole 协程实践，总结出 5 种经过生产环境验证的方案。
基于 FastCGI 的多版本 PHP-FPM 隔离
这是最基础的并行方式,通过编译或安装不同版本的 PHP，并为其配置独立的 PHP-FPM 进程（监听不同端口如 9000 和 9001），在 Nginx 配置中，利用 location 块或 if 条件，将请求分发到对应的 fastcgi_pass 端口。
# 旧版本 PHP 5.6
location /legacy/ {
fastcgi_pass 127.0.0.1:9000;
include fastcgi_params;
}
# 新版本 PHP 8.2 用于新接口
location /api/v2/ {
fastcgi_pass 127.0.0.1:9001;
include fastcgi_params;
}
优势：资源完全隔离，互不干扰。劣势：需要维护两套依赖库，磁盘占用高。
Nginx 层基于 URL/目录的灰度路由
衔接方案一,更精细的做法是按权重或 Cookie 进行灰度发布，给 10% 的用户设置 Set-Cookie: version=new，Nginx 通过 map 指令读取 Cookie 值，动态切换 upstream。
map $cookie_version $backend {
default legacy_server;
new new_server;
}
server {
location / {
proxy_pass http://$backend;
}
}
注意：此方案要求新旧代码的 Session 机制必须兼容（如 Redis 共享），否则用户会被迫重新登录。
代码层面的 "Feature Flag" 特性开关
无需运维介入,纯代码控制，引入一个配置文件 feature.php，通过全局函数判断当前请求是否走新逻辑。
// config.php
return [
'use_new_checkout' => $_ENV['APP_ENV'] === 'production' && rand(1,100) <= 20,
];
// 控制器内
if (feature_enabled('use_new_checkout')) {
(new NewCheckoutService())->handle();
} else {
(new LegacyCheckout())->handle();
}
进阶：结合数据库或 Redis 实时修改开关值，实现热更新，这是 Laravel Pennant 或 Toggler 包的核心思想。
消息队列异步解耦新旧业务
针对耗时的核心业务（如订单通知、日志分析），将新旧逻辑写入不同的队列主题，旧系统负责写入旧队列，新系统消费新队列，通过控制消费者进程数量，调节处理速度，实现“数据并行”，而非“请求并行”。
容器化（Docker）端口映射并行
这是最现代的解法,为旧应用构建 legacy:latest 镜像，新应用构建 new:latest，在 docker-compose.yml 中分别映射不同宿主机端口，通过 nginx-proxy 或 Traefik 动态路由。
services:
legacy:
image: legacy:latest
expose: ["8080"]
newapp:
image: new:latest
expose: ["8081"]
高频问答（Q&A）
问1：并行运行会话（Session）冲突怎么办？
答：务必统一 Session 存储到 Redis 或 Memcached，新旧代码的 session_name 必须一致，并且存储的数据结构要兼容（例如旧版存数组，新版要求对象，需做一层适配器）。
问2：数据库表结构不同，如何并行？
答：最佳的方案是双写，新代码写新表，同时异步同步到旧表（或反之），在读取时，优先读新库，失败回退读旧库，推荐使用 debezium 或简单的 binlog 监听实现。
问3：并行多久可以切全量？ 答：至少观察 1-2 个业务周期（如一周），重点监控两个指标：错误率（新旧差异不能超过 0.5%）和 性能耗时（新代码平均响应时间不得高于旧代码的 1.2 倍），并要随时准备执行“一键回滚”脚本。
问4：有没有更轻量的方案？
答：如果只是测试某个函数，可以用 apachebench 压测工具直接对两个端口发请求对比，不接入线上流量，但是真正的并行必须是真实流量才能暴露边界问题。
结语与最佳实践建议
并行运行不是目的,而是平滑过渡的手段，核心原则是：降低爆炸半径，建议遵循以下步骤：
- 先做静态代码扫描（如 PHPStan）找致命错误。
- 在灰度环境（模拟生产数据）试运行三天。
- 控制流量切换的比例梯度为：5% -> 20% -> 50% -> 100%。
- 保持旧环境至少保留一个月，以备故障回滚。
通过上述方案,你不必担心“最后一分钟的深夜大迁移”，让 PHP 升级变成一件从容的事情。技术债的偿还不是一蹴而就，而是分而治之。
