502错误本质是Nginx无法从FrankenPHP获取有效HTTP响应，主因包括代理配置错位（如误用fastcgi_pass）、启动模式不匹配（Server/Worker混淆）、进程未就绪、超时过短或权限/资源限制。
FrankenPHP 部署到 Linux 服务器出现 502 错误，本质是 Nginx（或其他反向代理）作为网关，无法从 FrankenPHP 进程获取有效响应。这和传统 PHP-FPM 场景逻辑一致，但关键差异在于：FrankenPHP 是基于 Swoole 的原生 HTTP 服务器，不依赖 FastCGI 协议，而是以 HTTP/1.1 或 HTTP/2 直连方式提供服务。因此，502 多数源于代理配置错位、进程未就绪或通信链路中断。
FrankenPHP 启动模式决定排查方向
FrankenPHP 支持两种部署模式：
-
Server 模式：FrankenPHP 自身监听端口（如 :8080），Nginx 用
proxy_pass http://127.0.0.1:8080转发； -
Worker 模式：FrankenPHP 作为 PHP 运行时嵌入 Caddy 或 Nginx 的子进程（需配合
frankenphpCLI +worker指令），此时它不独立监听端口，而是由 Web 服务器直接调用。
若你按 Server 模式配置却误用了 Worker 启动方式，或反之，Nginx 就会连接失败，直接返回 502。
Nginx 代理配置不匹配
常见错误包括：
-
proxy_pass指向了未启动的端口（如http://127.0.0.1:8080，但 FrankenPHP 实际监听:8000或未启用 HTTP server）； - 忘记设置必要的代理头，导致 FrankenPHP 无法正确解析请求（例如缺失
proxy_set_header Host $host;和proxy_set_header X-Real-IP $remote_addr;）； - 使用了
fastcgi_pass（适用于 PHP-FPM）而非proxy_pass（适用于 FrankenPHP HTTP server），这是最典型的配置混淆； - Nginx 的
proxy_read_timeout设置过短（如默认 60 秒），而 FrankenPHP 正在加载扩展或预热应用，首次响应较慢，超时后断连并报 502。
FrankenPHP 进程未正常运行或崩溃
- 执行
ps aux | grep frankenphp查看主进程是否存在； - 检查启动日志：FrankenPHP 默认将错误输出到
stderr，若用 systemd 管理，运行journalctl -u frankenphp -n 50 -f可实时查看； - 常见崩溃原因：PHP 扩展冲突（如 xdebug 在生产环境启用）、
.env文件语法错误、composer install未完成、或frankenphp.json配置中documentRoot路径不存在； - 若使用
frankenphp server命令启动，需确认是否加了-v参数调试，或是否被终端退出（未用nohup或 systemd 守护）。
权限与资源限制问题
立即学习“PHP免费学习笔记（深入）”；
- FrankenPHP 需要读取项目目录、写入
var/或storage/（Laravel 等框架），若运行用户（如www-data）无权限，会静默失败； -
ulimit -n过低（如默认 1024）会导致高并发下连接耗尽，Nginx 报connect() failed (24: Too many open files)，最终转为 502； - 内存不足时，FrankenPHP 可能被 OOM Killer 终止，
dmesg -T | grep -i "killed process"可验证。
不复杂但容易忽略细节。
