FrankenPHP本身不支持WebSocket反向代理，必须由Nginx等外部代理处理协议升级并透传TCP流量至独立运行的WebSocket服务（如Swoole），FrankenPHP仅负责HTTP请求。
FrankenPHP 本身不支持 WebSocket 反向代理 —— 它没有内置的 WebSocket 代理能力，不能像 Nginx 那样直接用 proxy_pass 转发 ws:// 或 wss:// 流量。 所以你不能在 frankenphp.yaml 里配个字段就让 WebSocket 过来；必须靠外部反向代理（比如 Nginx）前置处理 WebSocket 协议升级请求，再把原始 TCP 流量透传给后端 PHP 应用（如 Swoole、ReactPHP 或自研 WebSocket server）。
为什么 FrankenPHP 不能直接代理 WebSocket
FrankenPHP 是基于 Caddy 的 Go 实现封装，但当前（v1.1.x）的 frankenphp 模块仅接管 HTTP/HTTPS 请求并转发给 PHP-FPM 兼容接口。它不解析或透传 Upgrade: websocket 请求头，也不维持长连接生命周期 —— 这些都属于反向代理层的职责，而 FrankenPHP 的定位是「PHP 运行时」，不是「通用反向代理」。
常见错误现象：
• 前端 new WebSocket('wss://app.example.com') 报 WebSocket connection to 'wss://...' failed
• 浏览器 Network 面板显示 400 或 502，且响应体为空或含 Bad Request
• 后端 WebSocket server 日志无任何连接记录，说明连接根本没到达它
Nginx 作为 WebSocket 前置代理的标准配置
你需要用 Nginx（或其他支持 WebSocket 的反向代理）监听 443/80，处理 TLS 终止和协议升级，然后把原始 TCP 流量（非 HTTP）转发给本地运行的 WebSocket server（例如监听 127.0.0.1:8000 的 Swoole 服务）。FrankenPHP 在这里只负责常规 HTTP API，WebSocket 流量完全绕过它。
立即学习“PHP免费学习笔记（深入）”；
关键点：
-
proxy_http_version 1.1必须显式设置，否则 Nginx 默认用 HTTP/1.0，无法携带Upgrade头 -
proxy_set_header Upgrade $http_upgrade和proxy_set_header Connection "upgrade"缺一不可 —— 这是触发 WebSocket 协议升级的核心 -
proxy_pass http://backend_ws的目标地址必须是纯 HTTP（不是ws://），Nginx 不支持ws://作为proxy_pass协议 - 不要在
location /ws/块里加frankenphp指令 —— 那会让请求进 PHP-FPM，彻底破坏 WebSocket 握手
示例 Nginx 配置片段：
upstream backend_ws {
server 127.0.0.1:8000;
}
<p>server {
listen 443 ssl;
server_name app.example.com;</p><pre class='brush:php;toolbar:false;'>ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;
location /ws/ {
proxy_pass http://backend_ws;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 86400; # 长连接保活
}
location / {
# 正常 HTTP 请求交给 FrankenPHP
frankenphp;
}}
如何让 PHP WebSocket server 和 FrankenPHP 共存于同一域名
核心原则：路径分流 + 端口隔离。FrankenPHP 只处理它启动时监听的 HTTP 端口（如 8080），而你的 WebSocket server 必须独立运行在另一个端口（如 8000），由 Nginx 根据 location 路径决定流量去向。
使用场景：
- 前端通过
wss://app.example.com/ws/chat连 WebSocket，Nginx 将其转发到127.0.0.1:8000 - 前端通过
https://app.example.com/api/messages调用 REST 接口，Nginx 将其交给frankenphp，最终跑在 PHP 中 - 两者共享 session？不行 —— WebSocket server 通常不走 PHP-FPM，无法自动继承
$_SESSION。需改用 Redis 存储 session，并在两边手动读写
性能影响：Nginx 透传 WebSocket 是零拷贝级别的转发，几乎没有额外开销；但如果你误把 WebSocket 请求塞进 FrankenPHP，会导致握手失败或连接立即关闭 —— 这是最常踩的坑。
真正容易被忽略的是：FrankenPHP 的 frankenphp.yaml 文件里所有配置都只影响 HTTP 生命周期，对 WebSocket 流量完全无效。别试图在里面加 websockets: 或类似字段 —— 它不识别，也不会报错，只是静默忽略。
