FrankenPHP 安装时如何修改 Caddyfile 配置文件-php教程-PHP中文网

frankenphp 启动时默认读取当前工作目录下的 caddyfile，未找到即报错退出，不回退到内置配置。

frankenphp 安装时如何修改 caddyfile 配置文件

FrankenPHP 启动时会自动查找当前工作目录下的 Caddyfile，不依赖环境变量或额外参数。没找到就报错退出，不会 fallback 到内置默认配置。这点和原生 Caddy 一致，但容易被误以为“它自己有默认配置”。

常见错误现象：caddy run 或直接运行 FrankenPHP 二进制时报 open Caddyfile: no such file or directory，其实不是安装失败，只是缺这个文件。

路径必须是启动命令所在目录下的 Caddyfile，不是 /etc/caddy/Caddyfile，也不是容器里的 /app/Caddyfile（除非你 cd 进去再跑）
Docker 场景下，要确保 Caddyfile 被 COPY 或 volume 挂载到容器的工作目录（通常是 /app）
如果你用 docker-compose.yml 启动，检查 volumes: 是否把本地 Caddyfile 映射对了位置，别只挂了证书目录却漏了配置文件

FrankenPHP 的 php_server 指令本身不区分模式，模式切换靠 PHP 入口脚本逻辑（比如是否调用 frankenphp_handle_request()），但 Caddyfile 里得配对的 PHP 处理行为。

普通模式（兼容传统 PHP-FPM 行为）：

Academic Mentor

面向研究生的AI驱动研究顾问，提供研究评估、方案生成、文献分析、导师匹配及发表指导

下载

yourdomain.com {
    php_server
}

worker 模式（要求 PHP 入口已改写、常驻）：

yourdomain.com {
    php_server {
        root /app/public
        index index.php
    }
}

root 必须显式指定，否则 worker 模式下请求可能 404（因为常驻进程不自动推导文档根）
index 建议加上，避免某些框架路由 fallback 失效
别在 php_server 块里加 fastcgi_pass —— FrankenPHP 不走 FastCGI，这是 Nginx/FPM 的写法，写了会报错

Caddy 自动申请 Let’s Encrypt 证书的前提是：能从公网访问 80 和 443 端口，并且域名 DNS 已解析。本地开发或内网环境直接开 HTTPS 会卡在验证环节。

生产环境（有公网 IP + 域名）：直接写域名，Caddy 自动搞定一切
example.com { php_server }
本地开发（无域名或用 localhost）：必须显式禁用 HTTPS，否则启动失败
localhost:8080 { php_server } 或 :80 { php_server }
HTTP/3 支持无需额外开启，只要 HTTPS 正常，Caddy 默认启用；但 UDP 端口 443 必须开放（Docker 需加 - "443:443/udp"）
泛域名证书需要在 Caddyfile 里写成 *.example.com，且 Let’s Encrypt 要求该域名 DNS 记录可验证（不能只靠 hosts 文件）

FrankenPHP 不支持 caddy reload，改完 Caddyfile 必须重启进程。但可以少走弯路：

先用 caddy validate --config Caddyfile 检查语法（FrankenPHP 二进制也支持这个 flag）
Docker 场景下，别只 docker restart，要确认容器内 Caddyfile 确实更新了（docker exec -it frankenphp cat Caddyfile 看一眼）
如果用了 volumes: 挂载，注意 Windows/macOS 宿主机编辑保存后，Linux 容器有时会因 inotify 机制延迟感知变更，建议重启容器而非依赖热重载
日志里出现 listening on :443 或 listening on :80 才算真正加载成功，光看到 “starting” 不代表配置已生效