跳到主要内容

初始化

NPM Version Node Version

@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 文档

快速上手

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

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 鉴权,无需额外登录步骤。


安装 SDK

# 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/authregisterAuth
数据库@cloudbase/js-sdk/databaseregisterDatabase
云函数@cloudbase/js-sdk/functionsregisterFunctions
云存储@cloudbase/js-sdk/storageregisterStorage
数据模型@cloudbase/js-sdk/modelregisterModel
实时推送@cloudbase/js-sdk/realtimeregisterRealtime
AI@cloudbase/js-sdk/airegisterAi
云托管@cloudbase/js-sdk/cloudrunregisterCloudrun
MySQL@cloudbase/js-sdk/mysqlregisterMysql
提示
  • 内核 @cloudbase/js-sdk/app 必须引入
  • 实时推送模块依赖数据库模块,需先注册数据库
  • 按需引入可有效减少最终包大小,建议生产环境使用

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


初始化参数

通用参数

字段类型必填默认值说明
envstring-TCB 环境 ID。Node.js 云函数环境下不传则使用当前环境 ID
regionstringap-shanghai地域:ap-shanghai(默认)、ap-guangzhouap-singapore
langstringzh-CN指定语言:zh-CN(默认)、en-US
accessKeystring-Cloudbase API Key / Publishable Key,用于鉴权
timeoutnumber15000请求超时时间(ms)
注意

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

Node.js 端专属参数

Node.js 端

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

字段类型必填说明
secretIdstring腾讯云 API 密钥对,前往 腾讯云控制台/API 密钥管理 生成。也可通过环境变量 TENCENTCLOUD_SECRETID 配置
secretKeystring腾讯云 API 密钥对。也可通过环境变量 TENCENTCLOUD_SECRETKEY 配置
credentialsobject自定义登录私钥,包含 private_keyprivate_key_idenv_id,用于 createTicket 签发登录凭据。前往 云开发平台/身份认证/登录方式 的「自定义登录」下载私钥
contextobject函数型云托管入口函数的 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 端登录

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

方式适用场景是否需要登录交互
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 只能生成一次,并且是长期有效的、不能删除的,请妥善保管

Node.js 端鉴权

Node.js 端

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

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

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

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

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

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

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