FrankenPHP 启动 Symfony 时报 TypeError 是因未触发 Kernel::boot() 导致容器未初始化；需改用 HttpKernel::handle()、补全 $_SERVER 变量、显式配置 php.ini 并禁用 Doctrine 元数据缓存。
FrankenPHP 启动时 Symfony 报 TypeError：Argument #1 ($container) must be of type ContainerInterface
这是 FrankenPHP + Symfony 在启用严格类型（declare(strict_types=1);）后最典型的启动失败现象。根本原因不是 Symfony 写错了，而是 FrankenPHP 的 PHP 运行模式绕过了传统 CLI/Apache 的容器初始化流程 —— 它直接调用 index.php 入口，但未触发 Kernel::boot() 的完整生命周期，导致 $container 传入时为 null 或未完全实例化。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 检查你的
public/index.php是否仍沿用 Symfony 默认的「CLI 风格」引导逻辑（比如直接 new Kernel → boot → handle）。FrankenPHP 要求改用Symfony\Component\HttpKernel\KernelBrowser或更稳妥的HttpKernel::handle()手动调度路径 - 确认
Kernel类构造函数中没有依赖未注册的服务（例如在__construct()里就调用$this->getContainer()->get('xxx')），严格类型下这类提前取服务会直接炸 - 临时加一行日志验证容器状态：
var_dump($kernel->getContainer() instanceof ContainerInterface);—— 在 FrankenPHP 下很可能输出bool(false)
FrankenPHP 的 php.ini 加载顺序导致 Xdebug/Symfony Dev Tools 失效
FrankenPHP 自带嵌入式 PHP 解释器，它不读系统级 /opt/homebrew/etc/php/8.3/php.ini，而是优先加载自身 frankenphp.conf 中指定的配置，或当前工作目录下的 php.ini。这意味着你通过 pecl install xdebug 装的扩展、opcache.enable=0 等开发配置，在 FrankenPHP 下默认不生效。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 运行
frankenphp --version查看其内建 PHP 版本（如PHP 8.3.12），然后去对应源码或文档确认它支持的 ini 加载路径（常见为./php.ini或./conf/php.ini） - 在项目根目录新建
php.ini，显式启用关键扩展：zend_extension=xdebug.so<br>opcache.enable=0<br>error_reporting=E_ALL
- 不要依赖
php --ini输出 —— FrankenPHP 不走这个路径；改用frankenphp php -m | grep xdebug验证模块是否真实加载
Symfony 的 APP_ENV=dev 在 FrankenPHP 下无法触发 profiler / toolbar
FrankenPHP 默认以「production-like」模式运行，即使你设了 APP_ENV=dev 和 APP_DEBUG=1，Symfony\Component\HttpKernel\EventListener\DebugHandlersListener 可能因请求上下文缺失（如无 $_SERVER['REMOTE_ADDR'] 或 $_SERVER['HTTP_HOST']）而跳过 profiler 初始化。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 在
public/index.php开头强制补全关键服务器变量：$_SERVER['REMOTE_ADDR'] = $_SERVER['REMOTE_ADDR'] ?? '127.0.0.1';<br>$_SERVER['HTTP_HOST'] = $_SERVER['HTTP_HOST'] ?? 'localhost';
- 检查
config/packages/dev/web_profiler.yaml是否包含profiler: only_exceptions: false—— FrankenPHP 的非标准请求头可能被误判为「非交互请求」 - 用
curl -H "Accept: text/html" http://localhost:8080/测试，避免 CLI 模式下Accept头缺失导致响应被降级为 JSON
frankenphp-worker 模式下 Doctrine 实体无法自动重载
FrankenPHP 的 worker 模式复用 PHP 进程，Doctrine 的 proxy class 和 metadata cache 一旦生成就不会刷新 —— 即使你改了实体属性、加了 [ORM\Column] 注解，下次请求仍用旧缓存，导致 MappingException 或字段丢失。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 开发阶段禁用 metadata cache：在
config/packages/dev/doctrine.yaml中设doctrine.orm.metadata_cache_driver: pool: doctrine.system_cache_pool并确保该 pool 使用array驱动（非redis或filesystem） - 每次改实体后手动清 Doctrine 缓存：
php bin/console doctrine:cache:clear-metadata --env=dev，注意必须加--env=dev，否则清的是 prod 缓存 - 不要依赖
composer watch或文件监听自动 reload —— FrankenPHP worker 不支持热重启，改代码后需手动kill -SIGUSR1 $(pgrep frankenphp)触发 worker 重建
FrankenPHP 对 Symfony 的兼容性卡点不在功能层面，而在「生命周期假设」—— 它把 PHP 当作常驻服务来用，但 Symfony 默认按「一次请求、一次 boot」设计。所有报错几乎都源于某个环节假设了容器已就绪、缓存可失效、环境变量已完备。动手前先 frankenphp php -i | grep -E "(Loaded|extension)" 确认真实运行环境，比查文档更快定位问题根源。
