宝塔Swoole扩展WebSocket搭建【实战案例】-php教程-PHP中文网

必须完成php版本确认、swoole扩展安装、websocket服务启动、nginx反向代理配置（含upgrade/connection头）、服务器及安全组端口放行五步，缺一不可；否则前端会报“websocket connection failed”。

宝塔swoole扩展websocket搭建【实战案例】

要在宝塔面板上快速跑通一个可用的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 文件，内容如下：

$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

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错误。