初始化

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

提示

当前 @cloudbase/js-sdk 最新版本为 v3，该版本完全兼容 v2 版本，并与 HTTP API 全面对齐。自 v3.1 起已内置 Node.js 适配器，无需额外安装 @cloudbase/node-sdk。

若需使用 v2 版本，请参考v2 文档

传统模式初始化

当前文档适用于 PG 模式 环境，如果你使用的是传统模式，请参考初始化（传统模式）。

快速上手

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

Web 端
Node.js 端

npm install @cloudbase/js-sdk -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.database();
const result = await db.collection("todos").get();

获取 Publishable Key

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

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

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

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

// 在云函数/云托管中，SDK 自动读取环境鉴权信息
const db = app.database();
const result = await db.collection("todos").get();

提示

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

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

依赖包	用途	何时需要安装
`@cloudbase/signature-nodejs`	请求签名（TC3-HMAC-SHA256）	使用 `secretId` / `secretKey` 鉴权时
`jsonwebtoken`	自定义登录票据签发	调用 `auth.createTicket` 时
`ws`	WebSocket 连接	使用实时数据推送时

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

安装 SDK

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

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

# yarn
yarn add @cloudbase/js-sdk

全量引入：

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";
// 数据库模块
import { registerDatabase } from "@cloudbase/js-sdk/database";
// 云函数模块
import { registerFunctions } from "@cloudbase/js-sdk/functions";
// 云存储模块
import { registerStorage } from "@cloudbase/js-sdk/storage";
// 数据模型模块
import { registerModel } from "@cloudbase/js-sdk/model";
// 实时推送模块（需先注册数据库模块）
import { registerRealtime } from "@cloudbase/js-sdk/realtime";
// AI 模块
import { registerAi } from "@cloudbase/js-sdk/ai";
// 云托管模块
import { registerCloudrun } from "@cloudbase/js-sdk/cloudrun";
// MySQL 模块
import { registerMysql } from "@cloudbase/js-sdk/mysql";

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

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

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

模块名	包名	注册函数
内核	`@cloudbase/js-sdk/app`	-
登录	`@cloudbase/js-sdk/auth`	`registerAuth`
数据库	`@cloudbase/js-sdk/database`	`registerDatabase`
云函数	`@cloudbase/js-sdk/functions`	`registerFunctions`
云存储	`@cloudbase/js-sdk/storage`	`registerStorage`
数据模型	`@cloudbase/js-sdk/model`	`registerModel`
实时推送	`@cloudbase/js-sdk/realtime`	`registerRealtime`
AI	`@cloudbase/js-sdk/ai`	`registerAi`
云托管	`@cloudbase/js-sdk/cloudrun`	`registerCloudrun`
MySQL	`@cloudbase/js-sdk/mysql`	`registerMysql`

提示

内核 @cloudbase/js-sdk/app 必须引入
实时推送模块依赖数据库模块，需先注册数据库
按需引入可有效减少最终包大小，建议生产环境使用

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

# yarn
yarn add @cloudbase/js-sdk

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

依赖包	用途	何时需要安装
`@cloudbase/signature-nodejs`	请求签名（TC3-HMAC-SHA256）	使用 `secretId` / `secretKey` 鉴权时
`jsonwebtoken`	自定义登录票据签发	调用 `auth.createTicket` 时
`ws`	WebSocket 连接	使用实时数据推送时

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

初始化 SDK

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

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

提示

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

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

提示

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

<!-- 内核 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.js"></script>
<!-- 登录模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.auth.js"></script>
<!-- 数据库模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.database.js"></script>
<!-- 数据模型模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.model.js"></script>
<!-- 云函数模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.functions.js"></script>
<!-- 云存储模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.storage.js"></script>
<!-- 实时推送模块，引入前必须首先引入数据库模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.realtime.js"></script>
<!-- AI模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.ai.js"></script>
<script>
  // 注册功能模块
  registerAuth(cloudbase);
  registerDatabase(cloudbase);
  registerModel(cloudbase);
  registerFunctions(cloudbase);
  registerStorage(cloudbase);
  registerRealtime(cloudbase);
  registerAi(cloudbase);

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

注意

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

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

初始化参数

通用参数

字段	类型	必填	默认值	说明
`env`	`string`	是	-	TCB 环境 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）

注意

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

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.database();

注意

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

详情请参考：匿名登录

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

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

详情请参考：账号登录

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

const { data, error } = await app.auth.signInWithPassword({
  username: "your username",
  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 端鉴权​