frankenphp独立二进制默认只读当前目录下的caddyfile，不扫描子目录或上级目录，未找到时启用内置最小配置（仅localhost:80，无https/php），可通过语法错误触发解析报错来验证是否加载成功。
FrankenPHP独立二进制默认只读当前目录下的Caddyfile
它不会自动扫描子目录或上级目录，也不会 fallback 到系统路径；启动时若没找到 Caddyfile，就用内置最小配置（仅监听 localhost:80，不启用 HTTPS 或 PHP），你看到的可能是 404 或直接拒绝连接，而不是报错提示“配置文件缺失”。
验证是否加载成功最直接的方式是：在项目根目录放一个带语法错误的 Caddyfile，然后运行 frankenphp run —— 如果报 adapt: parsing caddyfile tokens: invalid directive，说明它确实读进去了；如果静默启动成功，大概率是根本没读到。
- 确保文件名严格为
Caddyfile（无后缀、大小写敏感） - Linux/macOS 下注意权限：
cat Caddyfile能读，不代表frankenphp进程有权限打开它（尤其挂载卷或打包后） - Windows 用户需确认换行符是 LF（Unix 风格），CRLF 可能导致解析失败且无明确提示
用 -config 参数强制指定Caddyfile路径最可靠
显式传参绕过默认查找逻辑，适合脚本化部署、多环境切换或路径不固定场景。参数优先级高于当前目录，且会校验文件存在性和基础语法。
常见写法：
frankenphp run -config ./conf/myapp.caddyfile frankenphp run -config /etc/myapp/Caddyfile frankenphp run -config $PWD/Caddyfile
注意：-config 必须紧跟在 run 子命令后，不能放在最后；路径支持相对和绝对，但不支持 glob（如 -config conf/*.caddyfile 无效）。
- 若路径不存在，会报
open /xxx/Caddyfile: no such file or directory - 若路径存在但为空，会报
unexpected end of JSON input（Caddy 解析器误判为 JSON 格式） - 该方式不改变工作目录，
root指令里的路径仍以当前目录为基准，不是-config所在目录
Docker中挂载Caddyfile要注意覆盖与路径一致性
Docker 场景下，Caddyfile 通常通过 volumes 或 COPY 放入容器，但容易因挂载顺序或路径错位导致失效。
典型有效结构：
docker run -v $(pwd)/Caddyfile:/app/Caddyfile -v $(pwd):/app dunglas/frankenphp
关键点：
-
/app/Caddyfile是 FrankenPHP 启动时默认查找位置，必须和挂载目标路径一致 - 不要只挂载
Caddyfile而不挂载项目代码 ——root public/会找不到public/目录，报 500 且日志里只显示“failed to open stream” - 使用
docker build时，COPY Caddyfile /app/Caddyfile必须在COPY . /app之后，否则会被覆盖
环境变量注入Caddyfile需要提前预留占位符
FrankenPHP 不支持运行时动态生成完整 Caddyfile，但允许在文件里用 {env.VAR_NAME} 插值，再配合 ENV 或 docker run -e 注入。
例如，在 Caddyfile 中写：
{env.HOSTNAME} {
root public/
php_server
}
然后启动时指定：
HOSTNAME=prod.example.com frankenphp run
限制很明确：
- 只支持
{env.XXX}形式，不支持 shell 变量展开（如$HOSTNAME）、不支持默认值语法（如{env.HOSTNAME|localhost}） - 插值只发生在 Caddy 解析阶段，不是字符串替换；如果
HOSTNAME为空，会变成{} {，导致语法错误 - 所有插值字段必须在
frankenphp run命令执行前已存在于进程环境，export后再调用才生效
真正难搞的不是怎么加载，而是加载后 root、php_server 和实际文件路径对不上——Caddyfile 里写的每一条路径，都得和运行时真实目录树严丝合缝，差一个 ./ 或少个 public/，就只能靠日志里那句模糊的 “failed to stat” 去猜。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
