FrankenPHP 1.5 升级报错的根本原因是项目代码或依赖未适配 PHP 8.2+ 的严格语义与移除特性，需聚焦 PHP 层兼容性修复，而非 FrankenPHP 配置。
确认真实错误来源
FrankenPHP 不会主动抛出 PHP 语法级错误——它只是更“诚实”地暴露原有代码在 PHP 8.2 下本就存在的问题。先定位报错类型：
- 看到
Fatal error: Uncaught TypeError或Cannot use string offset as array→ 属于 PHP 8.2 类型与字符串访问强化规则触发 - 出现
Deprecated: Function create_function() is deprecated→ 旧代码含已移除函数（PHP 8.0+ 完全删除） - 页面空白但日志无输出 → 检查
error_log路径是否被 FrankenPHP 的php.ini覆盖，或display_errors=Off且未启用日志写入 - 路由 404 或静态文件返回 → 不是 PHP 兼容问题，而是 FrankenPHP 的
router.php未正确转发请求（见下文）
重点修复 PHP 8.2 兼容性问题
FrankenPHP 1.5 默认启用 PHP 8.2 最严模式，以下几类问题高频出现：
-
字符串偏移访问：如
$str[0] = 'x'在 PHP 8.2 中禁止对字符串赋值，改用substr_replace()或转为数组操作 -
未定义数组键警告升级为 Error：PHP 8.2 对
$arr['missing']直接报Uncaught Error: Undefined array key，必须用isset($arr['missing'])或空合并运算符$arr['missing'] ?? 'default' -
废弃函数残留：检查是否有
mysql_*、ereg_*、session_register()、call_user_method()等，全部替换为 PDO/mysqli、preg_*、$_SESSION直接赋值等现代写法 -
对象转字符串强制失败：若类未定义
__toString()，(string)$obj在 PHP 8.2 中抛Fatal error，需补方法或改用get_class($obj)等安全替代 -
JSON 解码更严格：含非法控制字符或 UTF-8 双字节截断的 JSON，在
json_decode()后返回null，须加json_last_error()判断并清洗输入
验证 FrankenPHP 特有配置项
FrankenPHP 1.5 引入了新行为，需同步调整项目启动逻辑：
- 确保入口文件（如
public/index.php）顶部包含use Symfony\Component\Runtime\Runner\SymfonyRuntime;—— 若项目未使用 Symfony Runtime，需改用 FrankenPHP 推荐的轻量启动方式：<?php require __DIR__.'/vendor/autoload.php'; (new App\Kernel('prod'))->handle($_SERVER); - 检查
frankenphp_workers配置是否与项目并发模型冲突（如 Laravel Octane 已启用，再开 FrankenPHP Worker 会导致双重协程调度异常） - 若使用
router.php自定义路由，确认其返回的是Response实例，而非直接echo或exit，否则中断生命周期 - 禁用
opcache.enable_cli=1（FrankenPHP 运行于 CLI 模式），避免 OPcache 缓存污染导致类加载混乱
自动化检测与降级验证
别靠肉眼扫代码，用工具快速定位：
立即学习“PHP免费学习笔记（深入）”；
- 本地运行：
phpstan analyse --level=max --configuration=phpstan.neon src/（需安装phpstan/phpstan和phpstan/phpstan-phpunit） - 兼容性扫描：
phpcbf --standard=PHPCompatibility --runtime-set testVersion 8.2 ./src（配合PHPCompatibility规则集） - 临时降级验证：用 Docker 快速对比 PHP 8.1 vs 8.2 行为：
docker run --rm -v $(pwd):/app -w /app php:8.1-cli php public/index.phpdocker run --rm -v $(pwd):/app -w /app php:8.2-cli php public/index.php
FrankenPHP 1.5 升级不是障碍，而是推动项目清理技术债的契机。核心动作就三步：看日志定错误类型、按 PHP 8.2 规则修代码、用工具锁死遗留风险。只要不跳过测试环境验证，上线过程很平稳。
