frankenphp首次部署失败的8个关键坑：php.ini路径未显式指定、caddyfile中php指令漏配root和script_path、worker模式下框架未适配单例复用、https续期因端口未监听443而失败。
FrankenPHP 不是“装上就能跑”的黑盒，新手照着文档配完 Caddyfile 一启动就 502 Bad Gateway 或 空白页，根本不是配置写错了，而是几个关键点没对齐。下面这 8 个坑，90% 的首次部署失败都出在这里。
php.ini 路径没被 FrankenPHP 实际读取
很多人以为把系统全局的 /etc/php/8.2/cli/php.ini 改了就行，但 FrankenPHP 默认不走这个路径。它只认自己配置里显式指定的 php.ini，而且必须是完整路径、文件存在、权限可读。
- 检查
frankenphp.yaml或 Caddyfile 中是否设置了php.ini_path；没设就等于用空配置跑，opcache.enable、date.timezone全部失效 - 用
frankenphp -c /path/to/php.ini --version验证是否能加载成功；报错就说明路径不对或语法有误 - 别复用 PHP-FPM 的 ini 文件——它可能含
pm.*这类 FrankenPHP 完全忽略的指令，虽不报错但会干扰判断
Caddyfile 里 php 指令漏了 root 或 script_path
php 指令本身不自动推导项目根目录。你写 php { }，FrankenPHP 就默认去当前工作目录找 index.php，而不是你预期的 /var/www/html。
- 必须显式声明
root（静态资源路径）和script_path（PHP 入口所在目录），两者可以相同，但不能省 - 常见错误写法：
php { root /var/www/html }—— 这只告诉 Caddy 哪里找 CSS/JS，PHP 脚本仍会从当前目录加载 - 正确写法：
php { root /var/www/html script_path /var/www/html }，或者更安全地用绝对路径加index index.php
Worker 模式下框架没做“单例复用”适配
开启 workers.count: 4 后，Laravel/Symfony 的容器、数据库连接、Redis 实例不会自动变成常驻——它们仍按传统方式在每次请求初始化，worker 只是让进程不死，不是让对象自动共享。
- 必须手动把服务注册进容器的 singleton 生命周期，比如 Laravel 的
$this->app->singleton('redis', ...) - DB 连接要关掉
PDO::ATTR_PERSISTENT，否则多个请求共用一个连接句柄会出错；改用连接池或长连接管理器 - 别在
bootstrap/app.php里写依赖文件路径硬编码，worker 启动一次后，__DIR__指向的是 worker 初始化时的工作目录，不是每个请求的入口目录
HTTPS 自动续期失败但日志不报错
Caddy 的自动 HTTPS 默认监听 80 和 443 端口做 ACME 挑战，而 FrankenPHP 默认只开 :8080。如果你没在 Caddyfile 里显式绑定 :443，Let’s Encrypt 根本连不到你的服务，证书永远申请失败。
- 确保 Caddyfile 的 server 块监听了
:443，且宿主机防火墙放行该端口 - 本地测试时别用
localhost域名——Let’s Encrypt 不签，得用真实域名或自建 CA 测试 - 第一次启动时加
-watch参数，看终端输出有没有acme: Obtaining certificate；没有就说明挑战流程压根没触发
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
