快速开始

CloudBase JS SDK 通过 app.realtime() 提供与 Supabase Realtime 兼容的实时推送能力：

Broadcast：频道内低延迟消息广播，适合协作光标、临时信令等
Presence：同步频道内在线状态
Postgres CDC：监听 PostgreSQL 表的 INSERT / UPDATE / DELETE

全量引入 @cloudbase/js-sdk 后即可使用。同一 app 实例会复用同一个 Realtime 客户端。浏览器、Node.js、微信小程序均通过 app.realtime() 获取客户端。

与文档型数据库 watch() 的区别

collection.watch() 监听文档型数据库集合变更，属于 @cloudbase/js-sdk/realtime 模块（registerRealtime）。 app.realtime() 提供 Broadcast / Presence / PostgreSQL CDC，属于 @cloudbase/js-sdk/realtime-js 模块（registerRealtimeJs）。两者互不替代。文档型监听见 watch()。

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env-id",
  accessKey: "your-publishable-key",
});

const realtime = app.realtime();
const channel = realtime.channel("room");

channel.on("broadcast", { event: "cursor-pos" }, (payload) => {
  console.log(payload);
});

channel.subscribe((status, err) => {
  if (status === "SUBSCRIBED") {
    console.log("已订阅");
  }
  if (status === "CHANNEL_ERROR" || status === "TIMED_OUT") {
    console.error(status, err);
  }
});

订阅成功后即可 send() / track()。用完频道后务必清理，避免泄漏连接：

await channel.unsubscribe();
await realtime.removeChannel(channel);

// 或一次性清理并断开
await realtime.removeAllChannels();

环境	说明
Web	全量引入后直接 `app.realtime()`
Node.js	安装可选依赖 `ws`；云函数 / 云托管会自动读取鉴权
微信小程序	必须用 `app.realtime()`，不要 `new RealtimeClient()`。基础库需支持 `wx.connectSocket`

CloudBase 默认开启约 270s 的双连接热切，以适配网关连接最长存活时间。没有 window.Worker 的环境（如小程序）不会启用 Worker 心跳。登录、刷新 token、登出时，SDK 会自动同步 Auth 状态，一般无需手动 setAuth()。

能力概览

能力	监听类型	典型场景
Broadcast	`broadcast`	协作光标、临时信令、房间内消息
Presence	`presence`	谁在线、进出房间
Postgres CDC	`postgres_changes`	前端实时刷新 PostgreSQL 表数据

安装与注册

全量引入时 SDK 已自动注册 Realtime，直接调用 app.realtime() 即可。

按需引入时，文档型 watch() 与 app.realtime() 是两个模块，不要混用：

import cloudbase from "@cloudbase/js-sdk/app";
import { registerAuth } from "@cloudbase/js-sdk/auth";
// 文档型数据库 watch()，可选
import { registerDatabase } from "@cloudbase/js-sdk/database";
import { registerRealtime } from "@cloudbase/js-sdk/realtime";
// Broadcast / Presence / Postgres CDC
import { registerRealtimeJs } from "@cloudbase/js-sdk/realtime-js";

registerAuth(cloudbase);
registerDatabase(cloudbase);
registerRealtime(cloudbase);
registerRealtimeJs(cloudbase);

const app = cloudbase.init({ env: "your-env-id" });
const realtime = app.realtime();

模块	包名	注册函数	用途
文档型实时监听	`@cloudbase/js-sdk/realtime`	`registerRealtime`	`collection.watch()`
实时推送	`@cloudbase/js-sdk/realtime-js`	`registerRealtimeJs`	`app.realtime()`

提示

Node.js 使用实时推送时需安装 ws。微信小程序请使用 app.realtime()，不要单独 new RealtimeClient()，以便复用已注册的 wsClass / reqClass 适配器。

能力概览​

安装与注册​

能力概览

安装与注册