新手装FrankenPHP常见问题在于路径、监听地址、端口映射和上传限制未对齐：document-root必须精准指向public/目录；Caddyfile中root需同步匹配；默认监听127.0.0.1需改为0.0.0.0才能外网访问；启用HTTP/3须同时映射UDP 443端口；上传大文件需通过--max-memory-upload调大内存缓冲阈值。
新手装 FrankenPHP，最常卡在“看起来跑起来了，但打不开页面”或“报错没提示、日志是空的”。问题往往不出在 FrankenPHP 本身，而在于路径、监听地址、端口映射、上传限制这几个关键点没对齐。
路径和入口文件配错：404 却不报错
典型现象是访问首页返回 404 Not Found，但控制台和日志里没有任何错误。这基本不是 PHP 报错，而是 FrankenPHP 找不到入口或静态资源。
-
document-root 必须指向 public/ 目录，不是项目根目录。比如 Laravel 项目，要写
--document-root public/，不能漏掉斜杠，也不能写成./public或public（某些系统会因路径解析失败静默降级） -
.frankenphp.router.php 必须存在且可读，哪怕只有一行：
return ['index' => 'index.php'];。它不在？FrankenPHP 不会提醒，直接返回 404 - Caddyfile 中的
root路径也要同步匹配，比如写root * /app/public，就得确保容器内/app/public真实存在且权限正确（web 用户可读）
监听地址和网络模式不匹配：外部连不上
本地 curl http://localhost:8080 能通，但从其他机器或浏览器访问就超时或拒绝连接——大概率是绑定地址错了。
- 默认监听
127.0.0.1:8080，只允许本机回环访问。要对外服务，必须显式指定-- -listen 0.0.0.0:8080 - 用
--network host时，-p映射会被忽略，但0.0.0.0绑定仍不可少；否则宿主机其他 IP 无法访问 - Docker 模式下若监听
:80，非 root 容器会启动失败，要么加--user root，要么改用:8080
端口映射漏 UDP：HTTP/3 静默失效
想用 HTTP/3 却始终显示 h2 或 http/1.1？检查是否漏了 UDP 映射。
立即学习“PHP免费学习笔记（深入）”；
- 启用 HTTPS 时，Caddy 默认开 HTTP/3（QUIC），它强制依赖 UDP 443
- 必须加
-p 443:443/udp，光有-p 443:443/tcp不够 - 云服务器还要在安全组里单独放行
443/UDP，很多控制台默认只开 TCP，这点极易忽略 - host 模式下不用
-p，但得确认宿主机防火墙（如 ufw、firewalld）也放行了 UDP 443
上传失败或 $_FILES 为空：内存阈值太小
表单提交正常，但 $_FILES 始终为空，或大文件上传直接中断——不是权限问题，而是 FrankenPHP 的上传机制不同。
- 它默认把上传文件先缓存到内存，超过阈值才落盘；这个阈值默认只有 ~2MB
- 需在
php.ini或运行参数中调大：memory_limit和upload_max_filesize只影响 PHP 层，真正起作用的是 FrankenPHP 的--max-memory-upload参数 - 例如支持 50MB 上传：启动时加
--max-memory-upload 50M - 注意：这个值不是硬上限，只是内存缓冲区大小；超出后自动转临时磁盘，但磁盘路径需确保 web 用户有写权限
