概述

自 v3.1 版本起，@cloudbase/js-sdk 已内置 Node.js 适配器，无需额外安装 @cloudbase/node-sdk 或 @cloudbase/adapter-node，即可在 Node.js 环境（云函数、云托管、自建服务器等）中使用完整的云开发能力。

提示

node 版本要求 >= 16.0

安装

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

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

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

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

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

初始化

基本用法

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

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

初始化参数

字段	类型	必填	说明
`env`	`string`	否	TCB 环境 ID。云函数环境下不传则使用当前环境 ID
`accessKey`	`string`	否	Cloudbase API Key，优先级最高的鉴权方式。也可通过环境变量 `CLOUDBASE_APIKEY` 配置
`auth`	`object`	否	认证配置，包含 `secretId`、`secretKey`、`credentials` 等
`auth.secretId`	`string`	否	腾讯云 API 密钥对，前往腾讯云控制台/API 密钥管理生成。也可通过环境变量 `TENCENTCLOUD_SECRETID` 配置
`auth.secretKey`	`string`	否	腾讯云 API 密钥对。也可通过环境变量 `TENCENTCLOUD_SECRETKEY` 配置
`auth.credentials`	`object`	否	自定义登录私钥，包含 `private_key`、`private_key_id`、`env_id`，用于 `createTicket` 签发登录凭据。前往云开发平台/身份认证/登录方式的「自定义登录」下载私钥
`context`	`object`	否	函数型云托管入口函数的 `context` 参数，用于免签名调用
`timeout`	`number`	否	请求超时时间（ms），默认 `15000`

登录鉴权

服务端 SDK 可以使用 不同鉴权方式 访问云开发资源，支持以下鉴权方式（任选其一）：

鉴权方式	说明
默认鉴权（云函数/云托管环境）	无需传入参数，自动从环境变量读取密钥信息
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 管理获取

import tcb from "@cloudbase/node-sdk";

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

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

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

const app = cloudbase.init({
  env: "your-env-id",
  auth: {
    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",
});

环境信息

parseContext

app.parseContext(context: object): object

解析云函数入口函数的 context 参数，将运行时环境变量转换为结构化对象。

仅在云函数环境中有效

参数

context

object

云函数入口函数的 context 参数

返回值

Object

示例

基础示例

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

exports.main = async (event, context) => {
  const app = cloudbase.init({ env: "your-env-id" });

  const envObj = app.parseContext(context);
  console.log(envObj);
};

身份认证

服务端除了以下专属接口外，也可以调用客户端身份认证的所有接口，如邮箱登录、手机号登录、用户名密码登录、关联登录等，详见身份认证。

getUserInfo

auth.getUserInfo(): IGetUserInfoResult

获取当前请求的用户信息（同步方法，从云函数运行时环境变量中读取）。

同步方法，无需 await
仅在云函数/云托管环境中有效

参数

无参数

IGetUserInfoResult

Object

示例

基础示例

const cloudbase = require("@cloudbase/js-sdk");
const app = cloudbase.init({ env: "your-env-id" });

exports.main = async (event, context) => {
  const { openId, appId, uid, customUserId } = app.auth.getUserInfo();
  console.log(openId, appId, uid, customUserId);
};

getEndUserInfo

async auth.getEndUserInfo(uid?: string): Promise<IGetEndUserInfoResult>

获取终端用户详细信息。

不传 uid 时返回当前请求用户信息
传入 uid 时调用管理端接口查询指定用户
使用 API Key 或 Publishable Key 时无权限调用此接口

参数

uid

string

云开发用户身份标识。不传则从环境变量中读取当前用户信息

Promise

IGetEndUserInfoResult

userInfoEndUserInfo

云开发用户信息

openId

可选

string

微信 openId，非微信授权登录则为空

appId

可选

string

微信 appId，非微信授权登录则为空

uid

可选

string

用户唯一 ID

customUserId

可选

string

开发者自定义的用户唯一 ID

envName

可选

string

云开发环境名

nickName

可选

string

用户昵称

可选

string

用户登录邮箱

username

可选

string

用户登录用户名

hasPassword

可选

boolean

用户是否设置密码

gender

可选

"MALE" | "FEMALE" | "UNKNOWN"

用户性别

country

可选

string

地理位置（国家）

province

可选

string

地理位置（省份）

city

可选

string

地理位置（城市）

avatarUrl

可选

string

用户头像地址

requestId可选string

请求唯一标识

示例

获取当前用户
查询指定用户

const cloudbase = require("@cloudbase/js-sdk");
const app = cloudbase.init({ env: "your-env-id" });

exports.main = async (event, context) => {
  // 不传 uid，获取当前请求的用户信息
  const { userInfo } = await app.auth.getEndUserInfo();
  console.log(userInfo);
};

const cloudbase = require("@cloudbase/js-sdk");
const app = cloudbase.init({ env: "your-env-id" });

exports.main = async (event, context) => {
  const { userInfo, requestId } = await app.auth.getEndUserInfo(
    "target-user-uid"
  );
  console.log(userInfo);
};

queryUserInfo

async auth.queryUserInfo(query: IUserInfoQuery): Promise<any>

按条件查询用户信息。

支持按 uid、platform、platformId 三种维度查询
若指定 uid 则优先使用
使用 API Key 或 Publishable Key 时无权限调用此接口

参数

query

IUserInfoQuery

Promise

Object

示例

按 uid 查询
按手机号查询

const cloudbase = require("@cloudbase/js-sdk");
const app = cloudbase.init({ env: "your-env-id" });

exports.main = async (event, context) => {
  const res = await app.auth.queryUserInfo({ uid: "user-uid" });
  console.log(res.userInfo);
};

const cloudbase = require("@cloudbase/js-sdk");
const app = cloudbase.init({ env: "your-env-id" });

exports.main = async (event, context) => {
  const res = await app.auth.queryUserInfo({
    platform: "PHONE",
    platformId: "13800138000",
  });
  console.log(res.userInfo);
};

getClientIP

auth.getClientIP(): string

获取客户端 IP 地址。

同步方法，从环境变量 TCB_SOURCE_IP 中读取
仅在云函数/云托管环境中有效

参数

无参数

返回值

string

客户端 IP 地址

示例

基础示例

const cloudbase = require("@cloudbase/js-sdk");
const app = cloudbase.init({ env: "your-env-id" });

exports.main = async (event, context) => {
  const ip = app.auth.getClientIP();
  console.log("客户端 IP:", ip);
};

createTicket

async auth.createTicket(uid: string, options?: ICreateTicketOpts): Promise<string>

创建自定义登录凭据 Ticket，使用 RSA 私钥签发 JWT，客户端凭此 Ticket 可换取登录态。

使用前需在 init 时传入 auth.credentials（自定义登录私钥）
前往云开发平台/身份认证/登录方式，通过「自定义登录」下载私钥文件
需安装依赖：npm install jsonwebtoken

参数

uid

string

开发者自定义的用户唯一 ID（4~32 位，支持字母数字和部分特殊字符）

options

ICreateTicketOpts

Promise

string

自定义登录凭据 Ticket，格式为 "{private_key_id}/@@/{jwt_token}"

示例

基础示例

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

const app = cloudbase.init({
  env: "your-env-id",
  auth: {
    credentials: require("/path/to/tcb_custom_login.json"),
  },
});

exports.main = async (event, context) => {
  const ticket = await app.auth.createTicket("custom-user-id-123", {
    refresh: 3600 * 1000, // 1 小时刷新
  });
  console.log(ticket);
  // 将 ticket 返回给客户端，客户端调用 signInWithCustomTicket 完成登录
};

云开发能力

服务端 SDK 与客户端 SDK 共享同一套 API，以下各项云开发能力的调用方式与客户端完全一致，请参考对应文档：

能力	文档链接
云函数	云函数
云托管	云托管
云存储	云存储
文档型数据库	文档型数据库
MySQL 数据库	MySQL 数据库
数据模型	数据模型
AI	AI
APIs	APIs

提示

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

消息通知

sendTemplateNotification

app.sendTemplateNotification(params: object, opts?: object): Promise<object>

发送模板消息通知。

需在云开发平台/消息通知管理中预先配置通知策略
触发方式选择「手动触发」

参数

params

Object

opts

Object

Promise

Object

示例

基础示例

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

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

exports.main = async (event, context) => {
  const result = await app.sendTemplateNotification({
    notifyId: "your-notify-id",
    data: { orderId: "ORD-001", amount: 200 },
    url: "https://your-domain.com/order/detail",
  });
  console.log(result);
};

完整示例

以下是一个在云函数中综合使用各项服务端能力的示例：

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

const app = cloudbase.init({
  env: "your-env-id",
  auth: {
    credentials: require("./tcb_custom_login.json"), // 可选：自定义登录私钥
  },
});

const db = app.database();

exports.main = async (event, context) => {
  const { action } = event;

  switch (action) {
    // 身份认证（服务端专属）
    case "getUserInfo": {
      return app.auth.getUserInfo();
    }
    case "getEndUserInfo": {
      return app.auth.getEndUserInfo(event.uid);
    }
    case "createTicket": {
      return app.auth.createTicket(event.customUserId, {
        refresh: 3600 * 1000,
      });
    }

    // 数据库操作（与客户端调用方式一致）
    case "dbQuery": {
      return db.collection("todos").where({ completed: false }).get();
    }

    // 云函数调用（与客户端调用方式一致）
    case "callFunction": {
      return app.callFunction({
        name: "another-function",
        data: { key: "value" },
      });
    }

    // 云存储（与客户端调用方式一致）
    case "getTempFileURL": {
      return app.getTempFileURL({
        fileList: ["cloud://env-id.xxx/images/photo.png"],
      });
    }

    // 环境信息（服务端专属）
    case "parseContext": {
      return app.parseContext(context);
    }

    // 消息通知（服务端专属）
    case "notify": {
      return app.sendTemplateNotification({
        notifyId: "xxx",
        data: event.notifyData,
        url: event.notifyUrl,
      });
    }

    default:
      return { error: `未知操作: ${action}` };
  }
};

安装​

初始化​

基本用法​

初始化参数​

登录鉴权​

鉴权示例​

环境信息​

parseContext​

参数

返回

示例

身份认证​

getUserInfo​

参数

返回

示例

getEndUserInfo​

参数

返回

示例

queryUserInfo​

参数

返回

示例

getClientIP​

参数

返回

示例

createTicket​

参数

返回

示例

云开发能力​

消息通知​

sendTemplateNotification​

参数

返回

示例

完整示例​

安装

初始化

基本用法

初始化参数

登录鉴权

鉴权示例

环境信息

parseContext

身份认证

getUserInfo

getEndUserInfo

queryUserInfo

getClientIP

createTicket

云开发能力

消息通知

sendTemplateNotification

完整示例