跳到主要内容

WebSocket 协议支持

本文介绍如何在 Web 云函数中实现 WebSocket 长连接，支持服务端与客户端之间的双向实时通信。

什么是 WebSocket​

「WebSocket」是一种在单个 TCP 连接上进行全双工通信的协议，允许服务端主动向客户端推送数据。与传统的 HTTP 请求-响应模式不同，WebSocket 建立连接后可以保持长连接，实现服务端和客户端之间的实时双向数据传输。

主要特点：

  • 全双工通信：服务端和客户端可以同时发送和接收消息
  • 持久连接：建立连接后保持长连接，无需重复握手
  • 低延迟：消息传递实时高效，适合实时应用场景
  • 协议切换：通过 HTTP Upgrade 机制从 HTTP 协议升级为 WebSocket 协议

典型应用场景：

  • 实时聊天应用
  • 在线协作编辑
  • 实时数据监控
  • 游戏服务器
  • 实时通知推送

工作原理​

服务启动​

在支持 WebSocket 的 Web 云函数中，通过启动文件启动 WebSocket 服务器，服务器必须在 9000 端口 上监听。

建立连接​

  1. 客户端通过 ws:// 或 wss:// 协议向云函数发起连接请求
  2. 云函数平台将连接透传给运行环境中的 WebSocket 服务进程（9000 端口）
  3. 连接协商及后续通信完全由您的 WebSocket 服务端代码处理

连接生命周期​

  • 连接与实例映射：一次 WebSocket 连接的生命周期等同于一次函数调用请求
    • 连接建立 = 请求发起
    • 连接断开 = 请求结束
  • 实例映射：函数实例与连接是一一对应的，同一实例在某一时刻仅处理一个 WebSocket 连接，新连接会启动新的实例
  • 连接保持：连接建立后，实例持续运行，处理双向数据传输
  • 连接结束：当 WebSocket 连接断开时，对应的函数实例停止运行

使用限制​

在使用 WebSocket 时，需要注意以下配额限制：

限制项说明
空闲超时时间10 ~ 7200 秒，连接上无消息传输时的超时时间
执行超时时间必须 ≥ 空闲超时时间，函数的最大运行时长
单次消息大小最大 256KB
单连接传输速率最大 128KB/s
单连接请求 QPS最大 10 次/秒

连接断开与状态码​

不同的断开情况对应不同的函数状态码：

断开情况函数表现函数状态码
正常关闭
状态码为 1000、1010、1011		函数正常执行结束200
异常关闭
非标准关闭状态码		函数异常结束439 (服务端关闭)
456 (客户端关闭)
空闲超时
连接无消息传输超过配置时间		函数异常结束455
执行超时
连接持续时间超过函数最大运行时长		函数异常结束433

操作步骤​

步骤1：开启 WebSocket 协议支持​

在创建或编辑云函数时，需要在控制台开启 WebSocket 协议支持。

  1. 登录 云开发平台/云函数/函数列表
  2. 点击「新建云函数」或选择已有函数点击「编辑」
  3. 在「函数配置」中找到「WebSocket 协议」配置项

显示 WebSocket 协议开关和空闲超时时间配置

  1. 开启「WebSocket 协议」开关
  2. 设置「WebSocket 空闲超时时间」（范围：10-7200 秒）
  3. 确保「执行超时时间」≥「空闲超时时间」
  4. 点击「保存」完成配置

⚠️ 注意：WebSocket 协议一旦开启后不可取消，但空闲超时时间可以后续修改。

步骤2：安装依赖并编写服务端代码​

根据您使用的编程语言，安装对应的 WebSocket 库并编写服务端代码。WebSocket 服务器必须监听 9000 端口。

安装依赖

安装 ws 库：

npm install ws

在 package.json 中添加依赖：

{
    "dependencies": {
        "ws": "^8.0.0"
    }
}

编写服务端代码

使用 ws 库实现 WebSocket 服务器：

const WebSocket = require('ws');

// 创建 WebSocket 服务器，必须监听 9000 端口
const wss = new WebSocket.Server({ port: 9000 });

wss.on('connection', (ws) => {
    console.log('新连接建立');

    // 发送欢迎消息
    ws.send('欢迎连接到 WebSocket 服务');

    // 接收消息
    ws.on('message', (message) => {
        console.log('收到消息:', message.toString());

        // 回复消息
        const response = {
            type: 'response',
            data: message.toString(),
            timestamp: Date.now(),
        };
        ws.send(JSON.stringify(response));
    });

    // 连接关闭
    ws.on('close', () => {
        console.log('连接已关闭');
    });

    // 错误处理
    ws.on('error', (error) => {
        console.error('WebSocket 错误:', error);
    });
});

console.log('WebSocket 服务器已启动，监听端口 9000');

步骤3：部署云函数​

完成代码编写后，部署云函数：

  • 在控制台点击「部署」按钮
  • 或使用 CloudBase CLI：tcb fn deploy --httpFn

步骤4：客户端连接测试​

使用浏览器或 Node.js 客户端连接 WebSocket 服务：

// 浏览器端
const ws = new WebSocket('wss://your-function.run.tcloudbase.com');

ws.onopen = () => {
    console.log('连接已建立');
    ws.send('Hello, server!');
};

ws.onmessage = (event) => {
    console.log('收到消息:', event.data);
};

ws.onclose = () => {
    console.log('连接已关闭');
};

ws.onerror = (error) => {
    console.error('WebSocket 错误:', error);
};

高级用法​

1. 广播消息​

将消息发送给所有连接的客户端：

const WebSocket = require('ws');

const wss = new WebSocket.Server({ port: 9000 });

// 存储所有连接的客户端
const clients = new Set();

wss.on('connection', (ws) => {
    // 添加到客户端列表
    clients.add(ws);
    console.log(`新连接建立，当前连接数: ${clients.size}`);

    ws.on('message', (message) => {
        const msg = message.toString();
        console.log('收到消息:', msg);

        // 广播给所有客户端
        clients.forEach((client) => {
            if (client.readyState === WebSocket.OPEN) {
                client.send(
                    JSON.stringify({
                        type: 'broadcast',
                        data: msg,
                        timestamp: Date.now(),
                    })
                );
            }
        });
    });

    ws.on('close', () => {
        // 移除断开的客户端
        clients.delete(ws);
        console.log(`连接已关闭，当前连接数: ${clients.size}`);
    });
});

2. 心跳检测​

实现心跳机制保持连接活跃：

const WebSocket = require('ws');

const wss = new WebSocket.Server({ port: 9000 });

wss.on('connection', (ws) => {
    let isAlive = true;

    // 心跳检测：每 30 秒发送 ping
    const heartbeatInterval = setInterval(() => {
        if (!isAlive) {
            console.log('心跳超时，关闭连接');
            ws.terminate();
            return;
        }

        isAlive = false;
        ws.ping();
    }, 30000);

    // 收到 pong 响应
    ws.on('pong', () => {
        isAlive = true;
    });

    ws.on('message', (message) => {
        console.log('收到消息:', message.toString());
        ws.send(`回复: ${message.toString()}`);
    });

    ws.on('close', () => {
        console.log('连接已关闭');
        clearInterval(heartbeatInterval);
    });
});

3. 房间管理​

实现简单的房间功能，支持多个客户端加入不同房间进行分组通信：

const WebSocket = require('ws');

const wss = new WebSocket.Server({ port: 9000 });

// 房间管理
const rooms = new Map();

wss.on('connection', (ws) => {
    let currentRoom = null;

    ws.on('message', (message) => {
        try {
            const data = JSON.parse(message.toString());

            // 加入房间
            if (data.action === 'join') {
                currentRoom = data.room;

                if (!rooms.has(currentRoom)) {
                    rooms.set(currentRoom, new Set());
                }
                rooms.get(currentRoom).add(ws);

                ws.send(
                    JSON.stringify({
                        type: 'system',
                        message: `已加入房间: ${currentRoom}`,
                        roomSize: rooms.get(currentRoom).size,
                    })
                );
            }

            // 发送消息到房间
            if (data.action === 'message' && currentRoom) {
                const roomClients = rooms.get(currentRoom);
                roomClients.forEach((client) => {
                    if (client.readyState === WebSocket.OPEN) {
                        client.send(
                            JSON.stringify({
                                type: 'message',
                                room: currentRoom,
                                content: data.content,
                                timestamp: Date.now(),
                            })
                        );
                    }
                });
            }
        } catch (e) {
            console.error('消息处理错误:', e);
        }
    });

    ws.on('close', () => {
        // 离开房间
        if (currentRoom && rooms.has(currentRoom)) {
            rooms.get(currentRoom).delete(ws);

            // 清理空房间
            if (rooms.get(currentRoom).size === 0) {
                rooms.delete(currentRoom);
            }
        }
    });
});

客户端连接示例​

// 连接 WebSocket
const ws = new WebSocket('wss://your-service.run.tcloudbase.com');

// 连接建立
ws.onopen = () => {
    console.log('WebSocket 连接已建立');
    ws.send('Hello, server!');
};

// 接收消息
ws.onmessage = (event) => {
    console.log('收到消息:', event.data);

    try {
        const data = JSON.parse(event.data);
        console.log('解析的数据:', data);
    } catch (e) {
        // 处理非 JSON 消息
    }
};

// 连接关闭
ws.onclose = () => {
    console.log('WebSocket 连接已关闭');
};

// 错误处理
ws.onerror = (error) => {
    console.error('WebSocket 错误:', error);
};

// 发送消息
function sendMessage(msg) {
    if (ws.readyState === WebSocket.OPEN) {
        ws.send(msg);
    }
}

常见问题​

1. 连接无法建立怎么办？​

  • 检查是否在控制台开启了 WebSocket 协议支持
  • 确认 WebSocket 服务器正在监听 9000 端口
  • 确认使用正确的 WebSocket 地址（ws:// 或 wss://）
  • 检查云函数是否正常部署和运行
  • 查看云函数日志是否有错误信息

2. 连接频繁断开怎么办？​

  • 检查空闲超时时间配置是否合理（建议设置较大值，如 3600 秒）
  • 实现心跳机制保持连接活跃（每 30 秒发送一次 ping/pong）
  • 检查客户端网络是否稳定
  • 查看云函数日志，确认是否有异常错误导致连接断开
  • 确保执行超时时间 ≥ 空闲超时时间

3. 如何实现多人聊天室？​

参考本文「高级用法 - 房间管理」章节，使用 Map 或 Set 存储房间和连接信息。对于大规模应用，建议：

  • 使用 Redis 等外部存储管理连接状态和房间信息
  • 实现连接池管理
  • 考虑使用消息队列处理广播消息

4. 如何处理大量并发连接？​

  • 实例扩展：云函数会自动为每个 WebSocket 连接创建独立实例
  • 状态管理：使用 Redis 等外部存储共享连接状态
  • 消息队列：使用消息队列（如 TDMQ）处理广播和异步消息
  • 负载均衡：多个云函数实例自动负载均衡
  • 资源监控：关注函数实例数量和资源使用情况

5. 9000 端口被占用怎么办？​

云函数运行环境中，9000 端口是专门为 WebSocket 保留的，不会被其他服务占用。如果本地开发时遇到端口占用：

# 查找占用 9000 端口的进程
lsof -i :9000

# 终止进程（Mac/Linux）
kill -9 <PID>

6. 如何实现断线重连？​

客户端实现自动重连机制：

class ReconnectingWebSocket {
    constructor(url, maxRetries = 5) {
        this.url = url;
        this.maxRetries = maxRetries;
        this.retries = 0;
        this.connect();
    }

    connect() {
        this.ws = new WebSocket(this.url);

        this.ws.onopen = () => {
            console.log('连接已建立');
            this.retries = 0; // 重置重试计数
        };

        this.ws.onclose = () => {
            console.log('连接已关闭');
            this.reconnect();
        };

        this.ws.onerror = (error) => {
            console.error('WebSocket 错误:', error);
        };

        this.ws.onmessage = (event) => {
            console.log('收到消息:', event.data);
        };
    }

    reconnect() {
        if (this.retries < this.maxRetries) {
            this.retries++;
            const delay = Math.min(1000 * Math.pow(2, this.retries), 30000);
            console.log(`${delay}ms 后尝试重连 (${this.retries}/${this.maxRetries})`);

            setTimeout(() => {
                this.connect();
            }, delay);
        } else {
            console.error('达到最大重试次数，停止重连');
        }
    }

    send(data) {
        if (this.ws.readyState === WebSocket.OPEN) {
            this.ws.send(data);
        } else {
            console.warn('连接未打开，无法发送消息');
        }
    }
}

// 使用
const ws = new ReconnectingWebSocket('wss://your-function.run.tcloudbase.com');

相关文档​