frankenphp启动失败等故障需逐层排查：权限不足致静默退出、php: true未启用致空白页、static_files未开致404、proxy_pass斜杠引发request_uri异常、supervisor信号配置错误致worker重启、php_options未设致配置失效、trusted_proxies缺失致https重定向循环、base_uri冲突致路由干扰、sqlite路径相对致数据库打不开、ulimit过低致连接拒绝。
部署FrankenPHP时遇到启动失败、PHP脚本不执行、静态文件404、路由错乱、环境变量失效等具体故障，需要逐个定位底层配置与运行时行为差异。
服务启动后立即退出，日志无报错
检查frankenphp.sock所在目录权限：FrankenPHP默认以非root用户（如www-data）运行，若/var/run/frankenphp/目录属主为root且无组写权限，进程会静默退出。手动创建目录并赋权：sudo mkdir -p /var/run/frankenphp && sudo chown www-data:www-data /var/run/frankenphp && sudo chmod 755 /var/run/frankenphp。
确认frankenphp.yaml中pidfile路径可被写入，否则管理进程无法记录PID，systemd会判定为启动失败。
PHP脚本返回空白页，但Nginx显示200
方法一：在frankenphp.yaml中显式启用PHP处理——添加php: true字段。FrankenPHP默认只代理HTTP请求，不自动解析.php后缀，漏掉此项会导致所有PHP文件被当作静态资源返回原始代码。
方法二：检查index.php是否位于document_root指定路径下。FrankenPHP不会像Apache那样自动向上回溯查找DirectoryIndex，路径错一位就返回空响应。
【document_root必须精确到public或web子目录，不能指向项目根目录】
静态文件（CSS/JS）全部404
第一步：确认frankenphp.yaml中static_files配置已开启：static_files: true。
第二步：验证文件扩展名是否在默认白名单内。FrankenPHP默认只服务.css、.js、.png等常见类型，若使用.webp或.woff2，需手动追加到static_files.extensions列表。
第三步：检查Nginx反向代理配置中location /块是否错误地添加了try_files $uri @frankenphp——这会强制所有请求先查文件系统，而FrankenPHP的静态文件服务机制不依赖此指令，反而导致路径解析冲突。
$_SERVER['REQUEST_URI']值异常，含重复路径前缀
这是Nginx proxy_pass末尾斜杠引发的典型问题。当配置为proxy_pass http://127.0.0.1:8080/;（结尾有/），且FrankenPHP的base_uri未匹配时，Nginx会剥离原始URI前缀再拼接，造成REQUEST_URI丢失一级路径。
修复方式：将proxy_pass改为proxy_pass http://127.0.0.1:8080;（结尾无/），并在frankenphp.yaml中设置base_uri: "/app"（与Nginx location /app保持一致）。
通过supervisor管理时worker进程持续重启
FrankenPHP的worker模式依赖信号通信，supervisor默认发送TERM信号后等待10秒才发KILL，但FrankenPHP的worker收到TERM会立即退出，导致supervisor误判为崩溃。在supervisor配置中添加stopsignal=QUIT和stopwaitsecs=2，使其用优雅退出方式终止worker。
自定义PHP配置（如upload_max_filesize）不生效
FrankenPHP不读取系统级php.ini，必须在frankenphp.yaml中通过php_options注入：php_options: { upload_max_filesize: "64M", post_max_size: "64M" }。注意键名必须用下划线分隔，不能用短横线或驼峰。
修改后需重启FrankenPHP进程，仅重载Nginx无效。
HTTPS重定向死循环
当Nginx终止SSL并将X-Forwarded-Proto: https传给FrankenPHP时，若frankenphp.yaml中未设置trusted_proxies，框架无法识别真实协议，仍生成http://链接，触发301重定向回HTTPS，形成循环。在配置中加入trusted_proxies: ["127.0.0.1"]即可解决。
多应用共存时路由互相干扰
FrankenPHP本身不支持虚拟主机级别的隔离，多个应用必须通过base_uri严格划分路径空间。例如App A用base_uri: "/shop"，App B就必须用base_uri: "/blog"，两者不可嵌套或重叠。若共用根路径base_uri: "/"，后启动的应用会覆盖前者的路由表。
使用SQLite时提示“unable to open database file”
FrankenPHP worker进程的工作目录是启动时的当前路径，不是document_root。若SQLite数据库路径设为相对路径（如database.sqlite），实际会尝试在/opt/frankenphp之类的位置创建文件。必须使用绝对路径，例如/var/www/myapp/storage/database.sqlite，并确保www-data用户对该路径有读写权限。
日志中频繁出现“failed to accept connection: too many open files”
FrankenPHP对每个连接新建goroutine，系统默认的ulimit -n（通常1024）很快耗尽。在systemd服务文件中添加LimitNOFILE=65536，并执行sudo systemctl daemon-reload。该限制必须在FrankenPHP进程启动前生效，运行中调整无效。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
