FrankenPHP并非一键替换老项目的银弹，其稳定运行取决于是否识别出被遗忘的“默认假设”：PHP扩展缺失、$_SERVER变量差异、Worker模式下的全局状态泄漏、路径硬编码失效等隐性兼容问题需逐项排查修复。
FrankenPHP 对十年老项目不是“一键替换就能跑”，它能省掉 Nginx+PHP-FPM 的配置纠缠，但老项目往往在底层踩过太多历史坑，直接切过去容易触发隐性兼容断裂。核心判断是：**能否跑起来不难，但能否稳定、安全、按预期行为运行，取决于你是否提前识别出那些被遗忘的“默认假设”**。
PHP 版本与扩展 ABI 不匹配导致启动失败
FrankenPHP 官方二进制自带 PHP 运行时（目前主流是 8.2/8.3），它不依赖系统 PHP，也不加载系统 php.ini 或动态扩展。这意味着：
- 你原来靠
extension=apcu.so在系统 php.ini 里启用的 APCu 缓存，FrankenPHP 默认不带——得用install-php-extensions apcu显式安装； - 某些老项目依赖
mysql扩展（PHP 7.0 已废弃，7.4 彻底移除），而 FrankenPHP 内置的 PHP 8.2+ 根本没有这个模块，extension_loaded('mysql')直接返回 false，连index.php都可能 fatal error； - 像
ionCube Loader这类闭源加密扩展，FrankenPHP 的静态链接模型不支持——它只认标准 PHP 扩展 ABI，ionCube 是专为传统 SAPI 编译的，加载即 panic。
实操建议：迁移前先跑 frankenphp php-cli -m，比对老环境 php -m 输出，逐个补全缺失扩展；禁用所有非标准扩展（尤其是加密、混淆类）。
$_SERVER 变量污染与 CGI 路径解析差异
老项目常直接读取 $_SERVER['SCRIPT_NAME']、$_SERVER['PATH_INFO'] 做路由或路径拼接，而 FrankenPHP 在经典模式下走的是 Caddy 的 CGI 实现，不是传统 FPM 的 fastcgi_params 注入逻辑。关键差异点：
立即学习“PHP免费学习笔记（深入）”；
-
SCRIPT_FILENAME指向的是绝对路径（如/app/public/index.php），但老项目可能硬编码了相对路径逻辑，比如dirname($_SERVER['SCRIPT_FILENAME']) . '/../config.php'在容器内会越界； -
PATH_INFO的截断行为更严格：Nginx 的fastcgi_split_path_info允许模糊匹配，FrankenPHP 的splitCgiPath函数按 RFC 3875 精确分割，遇到非法 URI（如含未转义空格或控制字符）直接返回 400，老项目前端若发脏数据就挂； -
REQUEST_URI不再包含查询字符串（?后内容被剥离），老项目若用parse_url($_SERVER['REQUEST_URI'], PHP_URL_QUERY)取参数会得到 null。
实操建议：在入口 public/index.php 顶部加日志 dump 全部 $_SERVER，对比 Nginx+FPM 下的输出；把所有 $_SERVER 读取逻辑包一层适配函数，避免直取。
Worker 模式下全局状态泄漏引发并发错乱
这是十年老项目最危险的盲区：经典模式下每次请求都是干净进程，而 Worker 模式让 PHP 进程常驻，static 变量、全局数组、未重置的单例对象会跨请求残留。典型症状：
- 用户 A 登录后，用户 B 刷新页面看到 A 的用户名（Session ID 没变，但
$_SESSION数据被复用）； - 数据库连接未显式关闭，第 100 个请求时报
Too many connections（PDO 实例没析构）； - 老项目用
define('DEBUG', true)控制日志开关，Worker 复用后，后续所有请求都继承了第一个请求的DEBUG值。
实操建议：Worker 模式必须配合 laravel/octane 或自定义生命周期钩子，在每次请求结束时手动清理：unset($GLOBALS['xxx']);、gc_collect_cycles();、PDO::close()；禁用所有 define() 和 register_shutdown_function() 中的非幂等操作。
文件权限与运行时路径硬编码失效
FrankenPHP 进程以非 root 用户启动（默认 www-data），且工作目录固定为 Caddy 的 root 配置项所指位置。老项目常见硬伤：
- 写日志路径写死
/var/log/myapp/，但容器内该路径不存在或不可写，error_log()静默失败； - 上传目录用
__DIR__ . '/../uploads'拼接，而 FrankenPHP 的__DIR__指向的是内置 PHP 运行时路径，不是你的项目根目录； - 读取配置文件用
file_get_contents('/etc/myapp/config.json')，但容器里根本没挂载/etc/myapp。
实操建议：所有路径操作必须基于 getcwd() 或明确的环境变量（如 APP_BASE_PATH）；用 is_writable() 主动校验目录权限，失败时抛出清晰异常而非静默跳过。
真正卡住人的从来不是 FrankenPHP 本身，而是老项目里那些没人记得为什么这么写的 if (PHP_SAPI === 'cli') { ... } 分支、藏在 vendor 某个包里的 pcntl_fork() 调用、或者 config.php 里一行注释写着“此处不能删，否则支付宝回调失败”的神秘逻辑——这些才是迁移时最该花时间翻出来的硬币。
