FrankenPHP 404 通常因 Nginx 未正确转发请求所致：需确认 fastcgi_pass 指向其监听地址（如 unix socket 或端口），进程运行且 socket 可读写；root 必须精确指向 public/ 目录，try_files 需在 location / 块中并含 $query_string。
FrankenPHP 装完访问 404，基本不是 PHP 代码问题，而是请求压根没进 FrankenPHP —— 它根本没被 Web 服务器当作 PHP 运行时调用。
确认 FrankenPHP 是否真在处理请求
FrankenPHP 不是传统 PHP-FPM，它本身是二进制可执行文件，需由 Web 服务器（如 Nginx）通过 fastcgi_pass 显式指向它启动的监听地址（通常是 Unix socket 或 TCP 端口）。如果配置漏了这一步，Nginx 就会像对待一个不存在的后端一样返回 404。
- 检查 Nginx 的
location ~ \.php$块里是否有fastcgi_pass，且值指向 FrankenPHP 启动的地址，例如：fastcgi_pass unix:/var/run/frankenphp.sock;或fastcgi_pass 127.0.0.1:8080; - 运行
ps aux | grep frankenphp，确认 FrankenPHP 进程正在运行；再用ls -l /var/run/frankenphp.sock（或对应路径）验证 socket 文件存在且权限可读写 - 临时把
fastcgi_pass改成一个明显错误的地址（如fastcgi_pass 127.0.0.1:9999;），刷新页面——如果变成 502 而不是 404，说明原来确实是“没连上 FrankenPHP”，而非路由或文件问题
检查 Nginx 的 root 和 try_files 配置是否匹配项目结构
FrankenPHP 通常配合现代 PHP 框架（如 Laravel、Symfony）使用，这些框架要求 Web 根目录必须是 public/ 子目录。如果 Nginx 的 root 指向了项目根（如 /var/www/myapp），但实际入口是 /var/www/myapp/public/index.php，那么所有请求都会因找不到 index.php 而被 Nginx 直接判为 404。
- 确认
root指令末尾不带斜杠，且精确指向public/目录，例如：root /var/www/myapp/public; -
try_files必须放在location /块内，且包含$query_string，否则 GET 参数丢失，部分路由会失效：try_files $uri $uri/ /index.php?$query_string; - 在
public/index.php开头加<?php die('franken hit');，访问/或/test—— 如果没输出，说明try_files没兜住请求，或者root指错了位置
验证 FrankenPHP 的内置路由是否启用且未被覆盖
FrankenPHP 默认启用 “PHP App Router”，会自动将请求转发给 public/index.php，但这个行为依赖两个前提：一是 Nginx 正确传递了 SCRIPT_FILENAME，二是没有其他重写规则提前截断或重定向。
立即学习“PHP免费学习笔记（深入）”；
- 确保 Nginx 的
fastcgi_param SCRIPT_FILENAME使用的是$document_root$fastcgi_script_name，而不是硬编码路径 —— FrankenPHP 需要根据此变量定位真实文件 - 删掉所有自定义
rewrite规则，包括.htaccess（FrankenPHP 不读它）和 Nginx 中非必要的return或rewrite指令；只保留最简location /+try_files+location ~ \.php$三段 - 如果用了子目录部署（如
/myapp/），FrankenPHP 需要额外设置FRANKENPHP_PUBLIC_PATH环境变量，否则它会从/开始找index.php
最容易被忽略的是：FrankenPHP 启动时默认监听 Unix socket，但很多一键脚本或文档示例直接复制了 TCP 配置；或者 Nginx 配置里写了 fastcgi_pass，却忘了配 fastcgi_param 的关键项，导致 FrankenPHP 收到空请求路径而无法路由。调试时优先盯死 access.log 里有没有该请求记录、error.log 里有没有 connect() failed 或 no such file 类报错 —— 这些比看 PHP 日志更能快速定位卡在哪一层。
