唯一有效的环境变量是FRANKENPHP_WORKER_ENTRYPOINT，它仅接受一个相对或绝对路径字符串，指向可执行PHP入口文件；该变量只在php-server模式下生效，且必须在进程启动时注入并确保路径存在、可读、权限正确。
FRANKENPHP_WORKER_ENTRYPOINT 是唯一有效的环境变量
FrankenPHP 不识别 FRANKENPHP_WORKER、WORKER_SCRIPT 或其他自定义变量来指定 worker 脚本。唯一被官方解析并生效的环境变量是 FRANKENPHP_WORKER_ENTRYPOINT，它只接受一个**相对或绝对路径字符串**，且该路径必须指向可执行的 PHP 入口文件（如 index.php 或 public/index.php）。
- 在 Docker 中，必须通过
environment或env_file显式注入，例如：FRANKENPHP_WORKER_ENTRYPOINT=/app/public/index.php - 路径若为相对路径（如
index.php），则以 FrankenPHP 启动时的当前工作目录（pwd）为基准——这在容器中极易出错，强烈建议用绝对路径 - 该变量仅在 FrankenPHP 以
php-server模式启动时起作用；若用frankenphp-worker命令行直接运行，则忽略此变量，必须用--script参数 - 如果变量值为空、路径不存在、文件不可读或不是合法 PHP 脚本，FrankenPHP 会静默跳过 worker 模式，退化为普通请求模式（即每次请求都重新初始化）
为什么不能用 FRANKENPHP_CONFIG="worker ./index.php"
FRANKENPHP_CONFIG 是 Caddy 的配置注入机制，不是 FrankenPHP 自身的环境变量解析入口。它只在 Caddyfile 中通过 { frankenphp { {$FRANKENPHP_CONFIG} } } 这类模板语法展开后才生效，且展开后的内容必须符合 Caddy 的语法规范。
- 直接设
FRANKENPHP_CONFIG="worker ./index.php"会导致 Caddy 解析失败：缺少php指令块包裹，Caddy 会报错unknown directive 'worker' - 正确写法应是
FRANKENPHP_CONFIG="php { worker ./public/index.php }"，且确保 Caddyfile 中存在对应占位符 - 这个方式本质是动态生成 Caddyfile 片段，和环境变量指定 worker 脚本是两条路径：前者用于 Caddy 集成场景，后者用于纯
php-server场景 - 两者不可混用——同时设置
FRANKENPHP_WORKER_ENTRYPOINT和错误的FRANKENPHP_CONFIG，以前者为准，后者因语法错误可能让整个 Caddy 配置加载失败
常见错误：路径权限与上下文不一致
即使环境变量写对了，worker 脚本仍可能不触发，根本原因常出在路径解析上下文或文件权限上。
- Docker 容器中，
FRANKENPHP_WORKER_ENTRYPOINT=/app/public/index.php有效，但若COPY时没把文件真正复制到/app/下，或chown权限不对（如 www-data 无法读取），FrankenPHP 不报错，只跳过 worker - 在 systemd 服务中，
WorkingDirectory设置会影响相对路径解析，但FRANKENPHP_WORKER_ENTRYPOINT仍推荐用绝对路径，避免依赖该设置 - WordPress 等项目常默认用
index.php作为入口，但 FrankenPHP 要求该文件位于 Web 根目录下；若项目结构是/var/www/html/，则变量必须设为/var/www/html/index.php，而非./index.php - 修改环境变量后必须重启 FrankenPHP 进程（不是 reload），因为该变量只在进程启动时读取一次
验证是否生效的最简方法
别依赖日志或文档描述，直接看 FrankenPHP 启动时的输出和进程行为。
立即学习“PHP免费学习笔记（深入）”；
- 启动时加
-v（verbose）参数，正常会打印类似Worker mode enabled, entrypoint: /app/public/index.php的提示；没这行就说明变量未生效或路径无效 - 用
ps aux | grep php观察进程：worker 模式下应看到长期存活的frankenphp php-server进程，而不是瞬间启停的子进程 - 发两个快速连续请求，用
strace -p $(pgrep -f "frankenphp php-server") -e trace=clone,execve看是否复用同一进程（无clone调用）；若有大量clone，说明仍在“伪 worker”状态 - 检查
$_SERVER['FRANKENPHP_WORKER']是否为1（在 PHP 脚本中var_dump($_SERVER['FRANKENPHP_WORKER'] ?? 'not set');）——这是 FrankenPHP 注入的运行时标志，比环境变量更可靠
