Symfony迁移到FrankenPHP常驻模式报502，主因是环境变量未透传（APP_DEBUG须为字符串"0"）、dev入口残留（如app_dev.php）、路由监听冲突（端口占用或ACME干扰）；需配置frankenphp.yaml、删除dev入口、禁用ACME并显式启用HTTP。
将Symfony项目从传统Nginx+PHP-FPM迁移到FrankenPHP常驻模式时，常因环境变量未透传、调试入口残留、路由监听冲突导致502错误或dev工具意外暴露。这些不是配置遗漏，而是FrankenPHP与Symfony运行机制差异引发的硬性适配问题。
确认FrankenPHP已正确加载Symfony应用
进入项目根目录，执行frankenphp serve启动服务。若报错Failed to load configuration from "public/index.php"，说明FrankenPHP未识别到Symfony的前端控制器路径。
在项目根目录下创建frankenphp.yaml文件，写入以下内容：
server:
document_root: public
index_files: ["index.php"]
php_options:
APP_ENV: prod
APP_DEBUG: "0"
APP_SECRET: "your_production_secret_here"【APP_DEBUG必须用字符串"0"而非布尔false】——FrankenPHP通过环境变量注入PHP，PHP原生getenv()只返回字符串，false会被转成空字符串，导致Symfony误判为开发环境。
立即学习“PHP免费学习笔记（深入）”；
彻底清除dev调试通道
方法一：删除入口文件（推荐）
执行rm -f public/app_dev.php public/index_dev.php。Symphony 4+默认不再生成app_dev.php，但升级迁移项目可能残留该文件，FrankenPHP会将其识别为合法路由入口并响应，绕过prod环境校验。
方法二：重写Caddy路由规则（仅限FrankenPHP内置Caddy）
编辑frankenphp.yaml，在server块下追加http:配置：
http:
routes:
- match: [{ path: ["/app_dev.php", "/index_dev.php"] }]
handle:
- handler: static_response
status: 404
body: "Not found"这一步必须做。FrankenPHP的Caddy层在PHP执行前就完成路由匹配，不靠Symfony内核拦截。
修复路由监听端口与HTTPS自动续期冲突
第一步：检查当前监听端口是否被占用
执行lsof -i :8000（FrankenPHP默认端口），若输出非空，记下PID后执行kill -9 PID释放端口。FrankenPHP无法优雅接管已被占用的端口，强行启动会静默失败并退出进程。
第二步：禁用Let's Encrypt本地测试干扰
在frankenphp.yaml中，将https块下的acme配置设为disabled: true。生产环境启用ACME需域名解析就绪且80/443端口开放，本地开发强行启用会导致Caddy卡在证书申请环节，服务无法响应任何请求。
第三步：强制使用HTTP明文协议启动
执行frankenphp serve --http :8000。FrankenPHP默认尝试HTTPS，但无有效证书时会降级失败；显式指定--http可跳过证书验证流程，确保服务立即可达。
验证prod环境配置是否生效
访问http://localhost:8000/_profiler，应返回404页面。若显示Web Debug Toolbar，则说明APP_ENV未生效或config/packages/prod/web_profiler.yaml未被加载。
执行php bin/console debug:container --env=prod | grep debug，输出应为空。若有debug.*服务列出，证明prod环境下仍加载了开发专用服务，需检查config/packages/prod/目录下是否误存了debug.yaml或web_profiler.yaml。
执行php bin/console about，确认“Environment”字段显示为prod，“Debug mode”字段显示为Off。
