FrankenPHP 的 Caddy 服务行为由全局 servers 块控制，网络参数（端口、HTTP/3、超时）须显式配置；frankenphp 块仅管 PHP 运行时，num_threads 等参数必须置于其内且与 servers 同级；php_server 不支持 Laravel 路由重写，需手动配置 php 指令加 try_files；HTTPS 由 Caddy ACME 自动管理，禁用需显式设置 tls 或改用 :80。
如何在 Caddyfile 中覆盖默认服务器参数
FrankenPHP 的 Caddy 服务行为由 Caddyfile 全局 servers 块控制，不是靠环境变量或 CLI 参数。所有网络层配置（端口、协议、超时、HTTP 版本）必须显式写进 { servers { ... } } 块里，否则会回退到 Caddy 默认值（比如只监听 :443，不自动开 HTTP/3）。
常见错误是以为 frankenphp { ... } 块能改 HTTP 服务参数——它只管 PHP 运行时，不碰服务器监听逻辑。
- 必须把
servers放在 Caddyfile 顶部全局块，不能嵌套在站点块里 - 若没写
servers块，Caddy 默认只启用 HTTP/1.1 和 TLS，experimental_http3不生效 - 端口绑定需明确写出：
listen :80 :443 :443/udp，否则 UDP 端口不会开，HTTP/3 就跑不起来
{ servers {
listen :80 :443 :443/udp
protocol {
experimental_http3
}
timeouts {
read_header 30s
write 60s
}
} }
修改 PHP 线程与请求队列行为的正确位置
num_threads、max_threads、max_wait_time 这些参数属于 FrankenPHP 的运行时配置，只能放在 frankenphp { ... } 块里，且必须位于全局块中（即和 servers 同级），不能塞进站点块。
容易踩的坑：有人把 frankenphp { num_threads 8 } 写在 example.com { ... } 里面，结果完全不生效——Caddy 会静默忽略，线程数始终是默认的 auto（即 CPU 核心数）。
立即学习“PHP免费学习笔记（深入）”；
-
num_threads是初始线程池大小，建议设为 CPU 核心数 ×2；max_threads是上限，设为auto或具体数值均可 -
max_wait_time控制请求在队列里最多等多久，单位必须带后缀（如5s），写成5会被当秒但 Caddy 可能报错 - PHP ini 设置如
memory_limit也得放这里，不是php.ini文件——FrankenPHP 会覆盖运行时 ini 值
{ frankenphp {
num_threads 8
max_threads 16
max_wait_time 10s
php_ini memory_limit 512M
} }
为什么 php_server 指令不能替代手动路由
php_server 是一个快捷指令，等价于一组预设的 route 规则，但它只处理 .php 后缀和 /index.php 路径，对 Laravel/Symfony 的前端控制器模式（所有请求走 index.php）支持有限。一旦项目用了重写规则（如 try_files），就必须手动写 php 处理器。
典型表现是：首页能打开，但点击任何路由就 404，因为 php_server 没配 split_path 或 try_files，无法把 /user/profile 映射到 index.php。
- 用
php { root /app/public }替代php_server，可加split_path .php支持 PATH_INFO - Laravel 项目务必加
try_files {path} {path}/ /index.php?{query}，否则路由失效 -
root路径必须指向 public 目录，不是项目根目录，否则index.php找不到
HTTPS 证书路径与自动续期不可被覆盖
FrankenPHP 基于 Caddy，所以证书管理完全由 Caddy 的 ACME 流程接管。你不能通过 tls 指令指定自签名证书路径来绕过自动 HTTPS——Caddy 会优先走 ACME，除非你显式禁用：
- 要强制用本地证书，必须写
tls /path/to/cert.pem /path/to/key.pem，且不能有tls internal或 ACME 相关配置 - 若想停用自动 HTTPS，得把域名改成
:80或用http_port+https_port关闭 TLS 监听 - Caddy 的证书缓存路径固定为
/data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/，挂载 volume 时必须映射对，否则每次重启都重申请
最易忽略的是：Caddyfile 里只要写了域名（如 example.com），它就默认启用 ACME；哪怕你本地已有证书，不加 tls 指令，它也不会用。
