Bundle未被自动发现或注册，因FrankenPHP worker模式下容器只初始化一次且不依赖CLI预热；需显式注册Bundle、重建autoloader、避免build()中动态操作、统一环境变量管理。
Bundle 类未被自动发现或注册
FrankenPHP 的 worker 模式下，Symfony 容器只初始化一次，但 Kernel::registerBundles() 仍需在每次请求前执行 —— 这和传统 FPM 不同，它不依赖 CLI 环境下的 autoloader 预热逻辑。如果你用的是 Symfony 6.4+ 的「bundle 自动发现」（即 config/bundles.php 中未显式列出），而项目又没启用 SymfonyBundleFrameworkBundleFrameworkBundle 的自动扫描机制（比如删了 FrameworkBundle 或禁用了 kernel.bundles_autoconfigure），就会导致 Bundle 类根本没被加载。
实操建议：
- 确认
config/bundles.php中已显式注册关键 Bundle，例如SymfonyBundleFrameworkBundleFrameworkBundle::class => ['all' => true] - 检查
src/Kernel.php的registerBundles()方法是否被重写且漏掉了parent::registerBundles()调用 - 运行
php bin/console debug:container --env=prod（注意：必须在 prod 环境下跑，因为 FrankenPHP 默认走 prod）验证 Bundle 是否出现在列表中
autoloader 缓存未适配 FrankenPHP 生命周期
FrankenPHP 启动时会加载一次 Composer autoloader，之后所有请求复用该实例。如果项目使用了 composer dump-autoload --optimize 或启用了 classmap-authoritative，但后续又新增了 Bundle 类却没重新 dump，就会出现「类存在但无法 new」的静默失败 —— 错误不会抛出，只是容器构建跳过该 Bundle。
常见现象：php bin/console debug:bundle 找不到你的 Bundle，但 class_exists('App\Bundle\MyBundle') 返回 true；或者日志里有 Bundle "MyBundle" is not registered 但无堆栈。
立即学习“PHP免费学习笔记（深入）”；
实操建议：
- 在部署脚本中强制重建 autoload：
composer dump-autoload --classmap-authoritative --no-dev - 避免在
Kernel::registerBundles()中动态 require 或 include 文件（FrankenPHP 的常驻内存模型下，这类操作只生效第一次） - 确认
vendor/autoload.php是通过require_once加载，而非require（后者在多次请求中可能被跳过）
Bundle 的 build() 或 prepend() 方法执行时机异常
Symfony Bundle 的 build(ContainerBuilder $container) 和 prepend(Configuration $config) 在容器编译阶段触发。FrankenPHP 的 worker 模式下，这个阶段只发生一次（进程启动时），但如果你在这些方法里做了依赖环境变量、请求上下文或临时文件的操作（比如读取 $_SERVER['DOCUMENT_ROOT']、调用 file_get_contents('/tmp/config.json')），就可能因首次初始化时路径不存在、变量未设、或权限问题而静默失败。
实操建议：
- 把所有非静态配置提取到
config/packages/下的 YAML 文件中，避免在build()里硬编码路径或环境判断 - 如必须动态加载，改用
ContainerBuilder::addCompilerPass()并确保 pass 实现了__invoke()或继承自CompilerPassInterface，避免依赖全局状态 - 在
build()开头加日志：file_put_contents('/tmp/build.log', "build called at " . date('c') . " ", FILE_APPEND);，确认它是否真的被执行
环境变量与 FrankenPHP 的 env 配置冲突
FrankenPHP 默认从 Caddyfile 的 env 指令或系统环境读取变量，但 Symfony 的 .env 文件加载发生在 Kernel 构造函数中 —— 如果你用 APP_ENV=prod 启动 FrankenPHP，而 .env 里又写了 APP_ENV=dev，最终生效的是 .env 值，但 FrankenPHP 的进程级 env 变量（如 SYMFONY_DEPRECATIONS_HELPER）可能被忽略。
更麻烦的是：某些 Bundle（如 SensioFrameworkExtraBundle）会根据 APP_DEBUG 决定是否注册注解处理器，而这个值若在 FrankenPHP 启动后才被 .env 覆盖，就会导致注解失效且无提示。
实操建议：
- 删除项目根目录下的
.env文件，改用 FrankenPHP 的env指令统一管理：env APP_ENV prod<br>env APP_DEBUG false
- 在
Kernel.php构造函数开头加断点：var_dump($_ENV['APP_ENV'], $_SERVER['APP_ENV']);，确认哪个来源实际生效 - 避免在
config/bundles.php中用if ($_ENV['APP_ENV'] === 'dev')条件加载 Bundle，改用if (isset($_ENV['APP_ENV']) && $_ENV['APP_ENV'] === 'dev')并确保变量已加载
build() 方法里的文件操作和 .env 与进程 env 的优先级竞争。 
