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（截至 2025 年中），无需修改源码或打补丁。它用纯 PHP 实现 Reactor + Worker 模型，不依赖 ext-event 或 libevent，兼容性极好。

安装方式（推荐 Composer）：

立即学习“PHP免费学习笔记（深入）”；

composer require workerman/workerman

一个可直接运行的 ws.php 示例：

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 扩展来解耦，但得额外学一套通信协议。