PHPEnv配置WebSocket支持教程

phpEnv作为Windows下便捷的PHP集成环境虽不原生支持WebSocket，但通过Nginx反向代理配合独立WebSocket服务（如Workerman）即可完美实现ws://通信；本文直击核心痛点——详解如何正确配置Nginx的map指令、Upgrade/Connection头部、HTTP/1.1协议版本及超时参数，并强调后端必须脱离PHP-FPM独立运行、严禁混淆PHP脚本与WebSocket服务，手把手避开400/502常见陷阱，让开发者在本地快速打通实时通信链路。

phpEnv 本身不直接支持 WebSocket，它只是一个 Windows 下集成 PHP、Nginx、MySQL 环境的打包工具（类似 XAMPP），其内置 Nginx 默认**不启用 WebSocket 代理能力**，也不能直接运行 PHP WebSocket 服务（PHP 原生无常驻 WebSocket 服务器能力，需依赖 swoole 或 workerman）。 要让 phpEnv 环境跑通 WebSocket（ws://），本质是两件事： ① 让 Nginx 正确反向代理 WebSocket 请求（不是 PHP-FPM 处理）； ② 后端用独立进程跑 WebSocket 服务（如 workerman 监听 127.0.0.1:2346），不能走 php-fpm。 下面直奔实操：

确认 Nginx 版本是否 ≥1.3.13

打开 phpEnv 安装目录 → nginx\nginx.exe -v（或查看 nginx\conf\nginx.conf 顶部注释）。低于 1.3.13 的版本无法识别 Upgrade 头，会直接 400 或 502。常见 phpEnv 自带 Nginx 是 1.16+ 或 1.18+，基本够用；若太老，得手动替换 nginx.exe 和配套 conf 文件。

在 nginx.conf 的 http 块里加 map 指令

这是关键一步，很多教程漏掉它，导致 $http_upgrade 为空时 Connection 头被设成 "upgrade" 而非 "upgrade" 或 "close"，后端拒绝握手。

在 http { ... } 最上方（upstream 或 server 前）插入：

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

注意：'' 是空字符串，不是两个单引号；default 和 '' 后必须有空格再跟值；这行必须存在，否则 $connection_upgrade 变量未定义，proxy_set_header Connection $connection_upgrade 会出错。

配置 server 块代理到独立 WebSocket 服务

phpEnv 的默认 server 块通常只配了 location ~ \.php$，你需要新增一个匹配 WebSocket 路径的 location，且**不能和 PHP-FPM 共用**：

• 假设你的 WebSocket 后端用 workerman 跑在 127.0.0.1:2346
• 前端连接地址是 ws://localhost/ws，那就配 location /ws { ... }
• proxy_pass 必须指向 http://127.0.0.1:2346（不是 fastcgi://，也不是 php-fpm）
• proxy_http_version 1.1 必须显式写，不能依赖默认值
• proxy_set_header Upgrade $http_upgrade 和 proxy_set_header Connection $connection_upgrade 缺一不可
• proxy_read_timeout 建议设大些（如 86400），避免空闲断连

示例片段：

location /ws {
    proxy_pass http://127.0.0.1:2346;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $host;
    proxy_read_timeout 86400;
}

重启 Nginx 并验证代理是否生效

改完配置后，必须完整重启 Nginx（不是重载）：

进 phpEnv 控制台 → 点「Nginx」→ 「停止」→ 「启动」；或命令行进 phpEnv\nginx\ 目录执行：nginx.exe -s stop && nginx.exe。

验证方法：

• curl 测试握手头：curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" http://localhost/ws，应返回 HTTP/1.1 101 Switching Protocols
• 浏览器控制台连 new WebSocket("ws://localhost/ws")，看 Network → WS → Headers 是否有 Upgrade: websocket 和 Connection: Upgrade
• 如果报 Error during WebSocket handshake: Unexpected response code: 400，大概率是 map 没加或 proxy_set_header Connection 写成了字面量 "upgrade"（应为变量 $connection_upgrade）

真正容易被忽略的是：WebSocket 后端必须自己监听 TCP 端口并处理 HTTP 升级，phpEnv 里的 PHP-FPM 完全不参与这个过程——它只管 .php 请求。别试图用 index.php 启动 WebSocket 服务，那只会 502。

以上就是《PHPEnv配置WebSocket支持教程》的详细内容，更多关于phpenv的资料请关注golang学习网公众号！