PHP 8.4 不内置 WebSocket 服务器能力，无法原生实现完整握手与帧解析，必须依赖 Workerman 等第三方库；Workerman 5.x 全面支持 PHP 8.4，纯 PHP 实现，无需扩展，适合中小项目快速部署。
PHP 8.4 本身不内置 WebSocket 服务器能力，ext-websocket 仍未进入核心扩展，所以无法直接用 fsockopen 或 stream_socket_server 原生实现完整 WebSocket 握手与帧解析。必须依赖第三方库——而 Workerman 是当前最稳定、生产可用的选择。
为什么不能用 PHP 8.4 原生 socket 写 WebSocket 服务
WebSocket 协议要求严格的状态管理、掩码校验、帧分片、ping/pong 心跳、连接升级（HTTP 101）等逻辑。PHP 原生 socket 只提供字节流，不解析 HTTP 头、不处理 WebSocket 帧格式，手动实现极易出错且不可维护。
-
file_get_contents('php://input')在 upgrade 请求中为空，因为这不是 POST -
$_SERVER['HTTP_SEC_WEBSOCKET_KEY']可读，但后续 base64 + SHA1 + GUID 拼接响应头必须手算，稍错一位就连接失败 - 二进制帧的掩码（mask）、payload length 编码（7/7+16/7+64）、FIN/RSV/OPCODE 解析无标准函数支持
- 没有连接生命周期管理：超时、重连、广播、房间、心跳保活都得自己写
Workerman + PHP 8.4 的最小可行 WebSocket 服务
Workerman 5.x 已全面支持 PHP 8.4（截至 2024 年中），无需修改源码或打补丁。它用纯 PHP 实现 Reactor + Worker 模型，不依赖 ext-event 或 libevent，兼容性极好。
安装方式（推荐 Composer）：
立即学习“PHP免费学习笔记（深入）”；
composer require workerman/workerman
一个可直接运行的 ws.php 示例：
<?php
use Workerman\Worker;
use Workerman\Connection\TcpConnection;
require_once __DIR__ . '/vendor/autoload.php';
$ws_worker = new Worker('websocket://0.0.0.0:2346');
$ws_worker->count = 2;
$ws_worker->onMessage = function (TcpConnection $connection, $data) {
// $data 已自动解帧，是 string 或 array（若客户端发 JSON）
$connection->send('Hello ' . htmlspecialchars($data));
};
$ws_worker->onConnect = function ($connection) {
echo "New connection from {$connection->getRemoteIp()}\n";
};
$ws_worker->onClose = function ($connection) {
echo "Connection closed\n";
};
Worker::runAll();
启动后访问 ws://localhost:2346 即可测试。注意：onMessage 回调里的 $data 是已解码的 UTF-8 字符串，不是原始 WebSocket 帧。
常见踩坑点：SSL、跨域、Nginx 转发
本地开发直连没问题，但上线常遇到三类问题：
- 用
wss://时，Workerman 必须配置 SSL 上下文，不能只靠 Nginx 终止 TLS —— 否则onConnect拿不到真实 IP，且Sec-WebSocket-Protocol头可能被 Nginx 过滤 - Nginx 转发 WebSocket 需显式设置：
proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "upgrade"，缺一不可 - 浏览器报
Unexpected response code: 200，大概率是 Nginx 返回了 HTML 页面（如 404 页面）而非 101，检查location /是否误匹配了 WebSocket 路径 - PHP 8.4 的
mbstring.func_overload已废弃，若旧项目仍设为 1，会导致 Workerman 帧解析乱码，务必在php.ini中设为mbstring.func_overload = 0
替代方案对比：Swoole vs Workerman
有人会问为什么不选 Swoole？PHP 8.4 下 Swoole 5.x 确实支持更好性能，但它要求编译安装扩展，且对 Docker 多阶段构建、Alpine 等环境支持不如 Workerman 稳定。
- Workerman：纯 PHP，
require即用，适合中小项目、快速验证、共享主机（只要允许 long-running CLI 进程） - Swoole：需
pecl install swoole，协程模型更高效，但调试难度高，var_dump在协程里可能卡死，错误堆栈不直观 - 两者都不建议在 Apache mod_php 下运行 —— Apache 不支持长连接守护进程，必须用 CLI 模式启动
真正麻烦的从来不是“怎么写第一行 WebSocket 代码”，而是连接断开后消息如何补偿、用户状态如何持久化、集群下广播怎么跨机器同步——这些 Workerman 提供了 GatewayWorker 扩展来解耦，但得额外学一套通信协议。
