FrankenPHP 1.3 worker模式启动失败主因是--script未用绝对路径、--addr缺失、worker.php未按初始化/循环/清理三层结构编写、环境变量未通过系统变量注入。
FrankenPHP 1.3 的 worker 模式启动失败，通常不是单一配置错误，而是几个关键环节中某一处没对上。它不像传统 PHP-FPM 那样报错明确，很多问题会静默失败或只在 stderr 输出一行模糊提示。
脚本路径没写绝对路径
这是最常踩的坑。frankenphp-worker 命令必须用 --script 显式指定入口文件的绝对路径，比如 /app/public/worker.php。写成 public/worker.php 或 ./public/worker.php 都会失败——独立二进制不保证当前工作目录可靠，路径解析直接失败，进程退出并报 flag needs an argument: --script。
- 确认文件真实存在且 PHP 进程有读取权限
- 确保
vendor/autoload.php路径在 worker.php 中也用绝对路径 require - 不要依赖 Caddyfile 的相对路径逻辑，worker 启动是独立于 Caddy 配置加载的
缺少必要启动参数
除了 --script，--addr 也必须显式指定，例如 --addr :8080。漏掉这个参数，FrankenPHP 不会自动 fallback 到默认端口，而是监听失败或行为不可控，最终导致主进程判定 worker 启动超时而放弃。
- 多个 --addr 可同时指定，如
--addr :8080 --addr [::1]:8080 - 如果和 Caddyfile 中的 php_worker 共存，注意两者端口不能冲突
- 别混用旧命令：frankenphp php-server --worker 是 Caddy 插件模式语法，不适用于 1.3 独立二进制
worker.php 结构不符合三层模型
FrankenPHP 不会帮你重置全局状态。如果你把 public/index.php 直接当 worker 入口，首次请求后大概率出现 Class not found、DB 连接复用异常或内存持续增长。正确结构必须分三段：
立即学习“PHP免费学习笔记（深入）”；
- 初始化（一次）：require autoload、new Kernel、$kernel->boot()
-
请求循环（多次）：用
frankenphp_handle_request(function () { ... })包裹 request → handle → send 流程 -
清理（每次）：手动调用
gc_collect_cycles()，重置$_SERVER['REQUEST_URI']等变量
环境变量未提前注入
独立二进制打包后，.env 文件通常不会被自动加载。Dotenv::createUnsafeImmutable() 在常驻进程中只执行一次，若启动时没读到 APP_ENV，Kernel 就按默认值初始化，后续无法更改。
- 必须通过系统环境变量传入：
APP_ENV=prod APP_DEBUG=0 ./frankenphp-worker --script /app/public/worker.php --addr :8080 - 不要在 worker.php 里再 require dotenv，它已失效
- 检查扩展是否齐全（如 pdo_mysql、mbstring），缺失会导致 require 失败并中断初始化
