必须完成PHP版本确认、Swoole扩展安装、WebSocket服务启动、Nginx反向代理配置（含Upgrade/Connection头）、服务器及安全组端口放行五步，缺一不可；否则前端会报“WebSocket connection failed”。
要在宝塔面板上快速跑通一个可用的WebSocket服务，不是只装个Swoole扩展就完事——端口没放行、Nginx没配upgrade头、PHP版本和Swoole不匹配，任一环节出错都会导致前端报错“WebSocket connection to 'ws://...' failed”。下面按真实部署顺序，从环境确认到服务启动，一步一验。
确认PHP版本与Swoole兼容性
登录宝塔面板 → 进入「软件商店」→ 找到你网站正在使用的PHP版本（如PHP-8.0），点击「设置」→ 查看「PHP版本信息」页签里的实际版本号。注意：【必须确保命令行php -v和Web页面phpinfo()显示的版本完全一致】，否则扩展安装后Web端仍无法加载Swoole。若不一致，需在「设置默认版本」里强制切换，并重启PHP服务。
打开终端，执行 php --ri swoole 验证是否已启用。如果提示“Extension 'swoole' not present”，说明扩展未生效，不要跳过这步直接写服务代码。
安装Swoole扩展（两种路径）
方法一：宝塔图形化安装（推荐新手）
在PHP设置页 → 「安装扩展」选项卡 → 勾选「swoole」→ 点击安装 → 安装完成后重启对应PHP服务。这一步会自动写入 extension=swoole.so 到 php.ini，无需手动编辑。
方法二：命令行源码编译（适合定制需求）
进入对应PHP版本bin目录（如 /www/server/php/80/bin），执行：
./pecl install swoole
安装成功后，手动编辑 /www/server/php/80/etc/php.ini，在末尾添加：
extension=swoole.so
【切勿漏掉分号结尾，否则PHP启动失败】
编写并启动WebSocket服务端
第一步：在网站根目录新建 ws_server.php 文件，内容如下：
<?php
$server = new Swoole\WebSocket\Server("0.0.0.0", 9502);
$server->on('open', function ($server, $request) {
echo "Client {$request->fd} connected\n";
});
$server->on('message', function ($server, $frame) {
$server->push($frame->fd, "Echo: {$frame->data}");
});
$server->on('close', function ($server, $fd) {
echo "Client {$fd} closed\n";
});
$server->start();
第二步：通过宝塔终端进入网站根目录，执行：
php ws_server.php &
注意末尾的 & 符号，它让进程后台运行；不加的话关闭终端窗口服务就停了。
WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。
第三步：验证服务是否监听成功：
netstat -tuln | grep :9502
看到 tcp 0 0 *:9502 *:* LISTEN 即表示服务已就绪。
配置Nginx反向代理支持WebSocket
进入宝塔「网站」→ 选择你的域名 → 「设置」→ 「反向代理」→ 添加代理：
目标URL填 http://127.0.0.1:9502
然后在「自定义配置」框中粘贴以下内容（覆盖默认配置）：
location / {
proxy_pass http://127.0.0.1:9502;
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;
}
保存后重启Nginx。这一步缺一不可——没有 Upgrade 和 Connection 头，浏览器发起的WebSocket握手会被Nginx当作普通HTTP请求拒绝，返回400或502错误。
放行服务器端口并测试连接
在宝塔「安全」页面 → 「放行端口」→ 输入 9502 → 添加。
同时检查云服务商控制台的安全组规则，确保TCP 9502端口对0.0.0.0/0或你的测试IP开放。
新建 test.html 文件，放入网站根目录，内容含以下JS片段：
<script>
const ws = new WebSocket("ws://你的域名:9502");
ws.onopen = () => console.log("Connected");
ws.onmessage = e => console.log("Received:", e.data);
ws.send("Hello from browser");
</script>
用Chrome访问 http://你的域名/test.html，打开开发者工具 → Console，看到 "Connected" 即表示全流程打通。
