FrankenPHP不是PHP-FPM的即插即用替代品，因其SAPI行为、进程模型、扩展加载时机等存在本质差异，盲目同步迁移易引发shutdown函数失效、扩展异常、路由错乱及静态文件规则丢失等问题。
要，但前提是重构本身已明确要换 PHP 运行时栈，且团队对 frankenphp 的生命周期管理、SAPI 行为差异和静态文件处理有基本掌控力。盲目绑定迁移反而会放大风险。
为什么不能“顺手一起迁”
FrankenPHP 不是 drop-in 替换 php-fpm 的方案，它用 libphp 嵌入 Go 服务，SAPI 层行为、进程模型、信号处理、扩展加载时机都不同。常见踩坑点包括：
-
register_shutdown_function()在请求结束时可能不触发（尤其配合goroutine异步逻辑时） - 某些扩展（如
pcntl、posix）在 FrankenPHP 下不可用或行为异常 -
$_SERVER中的SCRIPT_FILENAME、PATH_INFO可能与 Nginx + php-fpm 场景不一致，路由中间件易出错 - 静态文件默认由 FrankenPHP 自己 serve，若原有 Nginx 配置含复杂 rewrite 或 auth 指令，直接绕过 Nginx 后规则失效
哪些重构场景适合同步迁移
满足以下任意一条，可考虑合并推进：
- 项目正从单体向 API-first 架构演进，且计划弃用传统
.php入口，改用index.php统一路由 +frankenphp内置 HTTP server - 已有容器化部署流程，且镜像中原本就用
php:alpine基础镜像 —— 改用docker.io/dunglas/frankenphp镜像成本低 - 重构中已引入
Swoole或ReactPHP类异步组件，说明团队接受非传统 PHP 生命周期，对frankenphp的 goroutine 模型适应性更强 - 明确需要
HTTP/3、QUIC或热重载能力，而这些是 FrankenPHP 原生支持、但需主动启用的功能
必须验证的三个关键点
哪怕重构和迁移同步进行，上线前也得实测这三项：
立即学习“PHP免费学习笔记（深入）”；
-
会话持久性：确认
session_start()后的写入是否真正落盘（尤其是用fileshandler 时），FrankenPHP 默认使用内存 session cache，容易造成登录态丢失 -
CLI 脚本兼容性：所有
bin/console、artisan、vendor/bin/phpunit等命令仍走标准 CLI SAPI，不受 FrankenPHP 影响，但要注意环境变量（如FRANKENPHP_DOCUMENT_ROOT）是否污染了 CLI 进程 -
错误日志流向：FrankenPHP 默认把
error_log()输出到 stdout，若原有日志收集器只监听php-fpm的slowlog或access.log，这部分日志会静默丢失
最常被忽略的是开发机本地运行模式和生产环境的配置割裂——比如用 frankenphp run 启动开发服务，但 CI/CD 流水线仍基于 php-fpm + nginx 测试，导致线上才暴露 SAPI 差异问题。迁移不是换二进制的事，是换执行契约。
