初始化

@cloudbase/js-sdk 是一个跨端 JavaScript SDK，支持在 Web 浏览器、Node.js 服务端（云函数、云托管、自建服务器等）、微信小程序、React Native 等多种运行环境中统一使用 JavaScript 访问 Cloudbase 服务和资源。

Beta

@cloudbase/js-sdk v4 目前是 Beta 版。npm 的 latest 仍是 v3，npm install @cloudbase/js-sdk 会安装 v3。正式环境请使用 JS SDK v3。试用 v4 请安装 @cloudbase/js-sdk@beta。

v4 已内置 Node.js 适配器，无需额外安装 @cloudbase/node-sdk。身份认证默认使用 GoTrue 客户端，通过 app.auth() 调用。

快速上手

只需 3 步即可开始使用云开发：

Web 端
Node.js 端

npm install @cloudbase/js-sdk@beta -S

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

const app = cloudbase.init({
  env: "your-env-id", // 替换为你的环境 ID
  accessKey: "your-publishable-key", // 替换为你的 Publishable Key
});

// 开始使用云开发能力
const db = app.rdb();
const { data, error } = await db.from("todos").select();

获取 Publishable Key

前往云开发平台 / API Key 配置生成。Web 端推荐使用 Publishable Key 鉴权，无需额外登录步骤。

npm install @cloudbase/js-sdk@beta @cloudbase/signature-nodejs -S

const cloudbase = require("@cloudbase/js-sdk");

const app = cloudbase.init({
  env: "your-env-id", // 替换为你的环境 ID
});

// 在云函数/云托管中，SDK 自动读取环境鉴权信息
const db = app.rdb();
const { data, error } = await db.from("todos").select();

提示

在云函数或云托管环境中，SDK 会自动从环境变量读取鉴权信息，无需手动配置密钥。

部分服务端功能依赖以下可选包，按需安装：

依赖包	用途	何时需要安装
`@cloudbase/signature-nodejs`	请求签名（TC3-HMAC-SHA256）	使用 `secretId` / `secretKey` 鉴权时
`ws`	WebSocket 连接	使用实时数据推送时

# 按需安装
npm install @cloudbase/signature-nodejs ws

已废弃、默认不挂载的模块

下面三个模块已废弃。安装 @cloudbase/js-sdk 时不会装上对应的包。要兼容旧调用，请单独安装，再引入注册函数，然后 init。app.database()、app.mysql()、app.rdb() 仍随主包提供。

模块	调用	安装	引入
文档型实时监听	`collection.watch()`	`@cloudbase/realtime`	`registerRealtime`
数据模型	`app.models`	`@cloudbase/model`	`registerModel`
HTTP API	`app.apis`	`@cloudbase/apis`	`registerApis`

npm install @cloudbase/realtime @cloudbase/model @cloudbase/apis -S

import cloudbase from "@cloudbase/js-sdk";
import { registerRealtime } from "@cloudbase/realtime";
import { registerModel } from "@cloudbase/model";
import { registerApis } from "@cloudbase/apis";

registerRealtime(cloudbase);
registerModel(cloudbase);
registerApis(cloudbase);

collection.watch() 来自 @cloudbase/realtime。app.realtime() 来自主包里的 registerRealtimeJs。

安装 SDK

包管理器
Node.js 服务端
CDN 全量引入
CDN 按需引入

# npm
npm install @cloudbase/js-sdk@beta -S

# yarn
yarn add @cloudbase/js-sdk@beta

全量引入：

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

const app = cloudbase.init({
  env: "your-env-id",
  region: "ap-shanghai", // 不传默认为上海地域
});

按需引入（减少包大小）：

// 内核（必须）
import cloudbase from "@cloudbase/js-sdk/app";
// 登录模块
import { registerAuth } from "@cloudbase/js-sdk/auth";
// PostgreSQL 数据库
import { registerMySQL } from "@cloudbase/js-sdk/mysql";
// 云函数模块
import { registerFunctions } from "@cloudbase/js-sdk/functions";
// 云存储模块
import { registerStorage } from "@cloudbase/js-sdk/storage";
// 数据模型模块（已废弃，需单独安装 @cloudbase/model）
import { registerModel } from "@cloudbase/model";
// 实时推送（Broadcast / Presence / Postgres CDC，app.realtime()）
import { registerRealtimeJs } from "@cloudbase/js-sdk/realtime-js";
// AI 模块
import { registerAi } from "@cloudbase/js-sdk/ai";
// 云托管模块
import { registerCloudrun } from "@cloudbase/js-sdk/cloudrun";

// 注册所需模块
registerAuth(cloudbase);
registerMySQL(cloudbase);
// ... 其他需要的模块

const app = cloudbase.init({
  env: "your-env-id",
  region: "ap-shanghai",
});

// 使用对应功能
const auth = app.auth();
const db = app.rdb();

模块名	包名	注册函数	全量入口
内核	`@cloudbase/js-sdk/app`	-	是
登录	`@cloudbase/js-sdk/auth`	`registerAuth`	是
云函数	`@cloudbase/js-sdk/functions`	`registerFunctions`	是
云存储	`@cloudbase/js-sdk/storage`	`registerStorage`	是
文档型数据库	`@cloudbase/js-sdk/database`	`registerDatabase`	是
MySQL / PostgreSQL	`@cloudbase/js-sdk/mysql`	`registerMySQL`	是
实时推送	`@cloudbase/js-sdk/realtime-js`	`registerRealtimeJs`	是
AI	`@cloudbase/js-sdk/ai`	`registerAi`	是
云托管	`@cloudbase/js-sdk/cloudrun`	`registerCloudrun`	是
文档型实时监听	`@cloudbase/realtime`	`registerRealtime`	否，已废弃
数据模型	`@cloudbase/model`	`registerModel`	否，已废弃
HTTP API	`@cloudbase/apis`	`registerApis`	否，已废弃

提示

内核 @cloudbase/js-sdk/app 必须引入
文档型实时监听、数据模型、HTTP API 已废弃，全量引入不会安装。见已废弃、默认不挂载的模块
实时推送（registerRealtimeJs）提供 app.realtime()，详见实时推送
按需引入可有效减少最终包大小，建议生产环境使用

# npm
npm install @cloudbase/js-sdk@beta -S

# yarn
yarn add @cloudbase/js-sdk@beta

部分服务端功能依赖以下可选包，按需安装：

依赖包	用途	何时需要安装
`@cloudbase/signature-nodejs`	请求签名（TC3-HMAC-SHA256）	使用 `secretId` / `secretKey` 鉴权时
`ws`	WebSocket 连接	使用实时数据推送时

# 按需安装
npm install @cloudbase/signature-nodejs ws

初始化 SDK

const cloudbase = require("@cloudbase/js-sdk");

const app = cloudbase.init({
  env: "your-env-id", // 替换为你的环境 ID
});

提示

4.x.x 表示使用最新版本，你可以设置为固定版本

<script src="https://static.cloudbase.net/cloudbase-js-sdk/4.1.0/cloudbase.full.js"></script>
<script>
  const app = cloudbase.init({
    env: "your-env-id", // 替换为你的环境 ID
    region: "ap-shanghai", // 不传默认为上海地域
  });
</script>

提示

4.x.x 表示使用最新版本，你可以设置为固定版本

<!-- 内核 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/4.1.0/cloudbase.js"></script>
<!-- 登录模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/4.1.0/cloudbase.auth.js"></script>
<!-- 数据模型模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/4.1.0/cloudbase.model.js"></script>
<!-- 云函数模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/4.1.0/cloudbase.functions.js"></script>
<!-- 云存储模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/4.1.0/cloudbase.storage.js"></script>
<!-- 实时推送（Broadcast / Presence / Postgres CDC，app.realtime()） -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/4.1.0/cloudbase.realtime-js.js"></script>
<!-- AI模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/4.1.0/cloudbase.ai.js"></script>
<script>
  // 注册功能模块
  registerAuth(cloudbase);
  registerModel(cloudbase);
  registerFunctions(cloudbase);
  registerStorage(cloudbase);
  registerRealtimeJs(cloudbase);
  registerAi(cloudbase);

  const app = cloudbase.init({
    env: "your-env-id", // 替换为你的环境 ID
    region: "ap-shanghai", // 不传默认为上海地域
  });
</script>

注意

功能模块必须在内核之后引入，并且登录模块必须引入

最新的版本号 version 可以前往 NPM 查看。

初始化参数

通用参数

字段	类型	必填	默认值	说明
`env`	`string`	是	-	CloudBase 环境 ID。Node.js 云函数环境下不传则使用当前环境 ID
`region`	`string`	否	`ap-shanghai`	地域：`ap-shanghai`（默认）、`ap-guangzhou`、`ap-singapore`
`lang`	`string`	否	`zh-CN`	指定语言：`zh-CN`（默认）、`en-US`
`accessKey`	`string`	否	-	Cloudbase API Key / Publishable Key，用于鉴权
`timeout`	`number`	否	`15000`	请求超时时间（ms）
`persistence`	`'local' \| 'session' \| 'none'`	否	`'local'`	登录态存储位置。`'local'` 写入本地存储，`'session'` 写入会话存储，`'none'` 不落盘
`debug`	`boolean`	否	`false`	为 `true` 时打开调试日志，包括 GoTrue 调试日志。登录流程打印 OAuth 调试信息。出现 `NETWORK_ERROR` 时，stderr 打印状态码、`requestId`；正文为字符串时再打印前 1024 个字符
`throw`	`boolean`	否	随 `authMode`	业务错误是否抛出。`supabase`（默认）为 `false`，返回 `{ code, message, requestId }`。`cloudbase` 为 `true`，抛出错误。显式传入的值优先。`throw: true` 时，认证接口改为抛错
`authMode`	`'supabase' \| 'cloudbase'`	否	`supabase`	认证实现。`supabase` 使用 GoTrue；`cloudbase` 为兼容模式，使用 CloudBase Auth
`auth`	`object`	否	-	身份认证配置，字段见下表

auth 字段如下。除 detectSessionInUrl 外，这些字段只作用于默认的 GoTrue 客户端。authMode: 'cloudbase' 时，只有 detectSessionInUrl 会传给 CloudBase Auth。

字段	类型	默认值	说明
`detectSessionInUrl`	`boolean \| function`	`true`	从当前 URL 恢复登录回调。传入函数时，返回 `true` 才把当前地址当成回调。设为 `false` 则关闭
`persistSession`	`boolean`	见说明	是否把登录态写入本地存储。未设置时，`persistence` 不是 `'none'` 则为 `true`。显式设置后优先于 `persistence`
`autoRefreshToken`	`boolean`	见说明	是否在 access token 过期前自动刷新。未设置时与最终的 `persistSession` 相同
`flowType`	`'implicit' \| 'pkce'`	`'implicit'`	OAuth 回调方式。`'implicit'` 从 URL hash 读取令牌。`'pkce'` 用查询参数中的授权码换会话

auth 中的其他字段会原样传给 GoTrue。secretId、secretKey、sessionToken、secretType、credentials 不会传入。url、headers、fetch、storage、storageKey 由 SDK 填写，auth 里的同名字段不生效。storageKey 固定为 cloudbase-auth-js-${env}。

注意

当前使用的环境所属地域，必须与当前指定的地域信息一致！

timeout 默认值说明

timeout 的默认值因运行环境而异：

Web / 小程序等非 Node.js 环境：默认 15000（15 秒）。
Node.js 环境（云函数、云托管、自建服务器等）：默认不设置超时（不限制），以适配服务端可能存在的长耗时请求。如需限制超时，请显式传入 timeout 参数。

无论何种环境，显式传入 timeout 时均以传入值为准（取值范围最大 10 分钟）。

Node.js 端专属参数

Node.js 端

以下参数仅在 Node.js 环境中有效。

字段	类型	必填	说明
`secretId`	`string`	否	腾讯云 API 密钥对，前往腾讯云控制台/API 密钥管理生成。也可通过环境变量 `TENCENTCLOUD_SECRETID` 配置
`secretKey`	`string`	否	腾讯云 API 密钥对。也可通过环境变量 `TENCENTCLOUD_SECRETKEY` 配置
`credentials`	`object`	否	自定义登录私钥，包含 `private_key`、`private_key_id`、`env_id`，用于 `createTicket` 签发登录凭据。前往云开发平台/身份认证/登录方式的“自定义登录”下载私钥
`context`	`object`	否	函数型云托管入口函数的 `context` 参数，用于免签名调用

SYMBOL_CURRENT_ENV

cloudbase.SYMBOL_CURRENT_ENV;

初始化时使用该字段，可指定请求当前云函数或云托管的环境。仅在云函数或云托管环境中生效。

注意

在云函数或云托管中，如在初始化 init({}) 未指定 env 参数，则默认使用当前环境 ID，不再使用云开发默认环境。如需要使用云开发默认环境，可以指定 init({env: tcb.SYMBOL_DEFAULT_ENV})。

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

// 取当前云函数的环境初始化
const app = cloudbase.init({ env: cloudbase.SYMBOL_CURRENT_ENV });

exports.main = async (event, context) => {
  // 业务逻辑
};

初始化后需要完成鉴权才能使用云开发能力。Web 端和 Node.js 端鉴权方式不同：

Web 端使用 C 端 用户权限，支持以下登录方式：

方式	适用场景	是否需要登录交互
Publishable Key	公开资源访问，最简方式	❌ 无需登录
匿名登录	无需注册即可使用	❌ 无需登录
账号密码登录	需要用户身份识别	✅ 需要

Publishable Key（推荐）
匿名登录
账号登录

Publishable Key 可以安全暴露在浏览器中，用于请求公开访问的资源，无需额外登录步骤。详细介绍请参考文档说明。

获取方式： 前往云开发平台 / API Key 配置生成。

const app = cloudbase.init({
  env: "your-env-id",
  accessKey: "your-publishable-key", // 填入生成的 Publishable Key
});

// 无需额外登录
const db = app.rdb();

注意

Publishable Key 只能生成一次，并且是长期有效的、不能删除的，请妥善保管

详情请参考：匿名登录

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

const auth = app.auth();
const { data, error } = await auth.signInAnonymously();

详情请参考：账号登录

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

const auth = app.auth();
const { data, error } = await auth.signInWithPassword({
  email: "user@example.com",
  password: "your password",
});

Node.js 端鉴权

Node.js 端

服务端支持多种鉴权方式访问云开发资源（任选其一）。

鉴权方式	说明	适用场景
默认鉴权（云函数/云托管环境）	无需传入参数，自动从环境变量读取密钥信息	云函数、云托管
API Key	将服务端 API Key 配置到环境变量 `CLOUDBASE_APIKEY`，SDK 自动读取	自建服务器
Publishable Key	在 `init` 中传入 `accessKey`，使用匿名角色身份访问	公开资源访问
`secretId` + `secretKey`	在 `init` 中显式传入腾讯云 API 密钥对	自建服务器
`context`	云托管场景，通过入口函数 `context` 参数实现免签名调用	函数型云托管

云函数环境（默认鉴权）
云托管环境
Publishable Key
secretId + secretKey
API Key

在云函数环境中，SDK 会自动从环境变量中读取鉴权信息，此鉴权信息为临时访问凭证，无需手动配置。

const cloudbase = require("@cloudbase/js-sdk");

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

exports.main = async (event, context) => {
  // 直接使用各项云开发能力
};

在函数型云托管环境中，通过传入 context 参数实现免签名调用。

💡 注意：如果传入了 context 参数但没有 env 参数，则会使用 context 中的 envID 参数作为环境 ID。

const cloudbase = require("@cloudbase/js-sdk");

exports.main = async (event, context) => {
  const app = cloudbase.init({
    context,
  });
  // 使用各项云开发能力
};

Publishable Key 详细介绍请参考文档说明。

用户权限：匿名用户权限
有效期：长期有效
获取方式：通过云开发平台/ApiKey 管理获取

const cloudbase = require("@cloudbase/js-sdk");

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

前往腾讯云控制台/API 密钥管理生成密钥对。

const cloudbase = require("@cloudbase/js-sdk");

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

可以通过环境变量 CLOUDBASE_APIKEY 配置，在云函数中开启 API key设置，添加 CLOUDBASE_APIKEY，SDK 自动读取。

const cloudbase = require("@cloudbase/js-sdk");

// 无需显式传入，SDK 自动从环境变量读取
const app = cloudbase.init({
  env: "your-env-id",
});

提示

服务端在不使用 API Key 或 Publishable Key 时，默认使用管理员权限，除此之外，接口签名、参数和返回值均与客户端一致。

快速上手​

已废弃、默认不挂载的模块​

安装 SDK​

初始化参数​

通用参数​

Node.js 端专属参数​

SYMBOL_CURRENT_ENV​

登录鉴权​

Web 端登录​

Node.js 端鉴权​