初始化

@cloudbase/manager-node 支持开发者通过接口形式对云开发提供的云函数、数据库、文件存储等资源进行创建、管理、配置等操作

安装 SDK

npm

npm install @cloudbase/manager-node -S

yarn

yarn add @cloudbase/manager-node

pnpm

pnpm add @cloudbase/manager-node

初始化 SDK

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: "your-secret-id",
  secretKey: "your-secret-key",
  envId: "your-env-id" // 替换为您的环境 ID
})

// 获取各功能模块
const { database, functions, storage, env, commonService } = app

如果需要管理多个腾讯云账号下的云开发服务，你也可以选择使用构造方法 new CloudBase() 初始化 SDK，每次初始化都会得到一个全新的 CloudBase 实例。

import CloudBase from '@cloudbase/manager-node'

// 管理账号 A 的环境
const appA = new CloudBase({
  secretId: "account-a-secret-id",
  secretKey: "account-a-secret-key",
  envId: "account-a-env-id"
})

// 管理账号 B 的环境
const appB = new CloudBase({
  secretId: "account-b-secret-id",
  secretKey: "account-b-secret-key",
  envId: "account-b-env-id"
})

初始化参数

字段	类型	必填	说明
envId	string	否	TCB 环境 ID，在 云开发控制台 概览页面获取。不填使用默认环境，因为后续的很多接口依赖于环境，在未传递的情况下，需要通过 addEnvironment() 添加环境方可进行后续接口调用
secretId	string	否	腾讯云 API 固定密钥对 secretId，前往 腾讯云控制台/API密钥管理 生成。secretId 与 secretKey 必须同时传递，在云函数内执行可不填
secretKey	string	否	腾讯云 API 固定密钥对 secretKey，前往 腾讯云控制台/API密钥管理 生成。secretId 与 secretKey 必须同时传递，在云函数内执行可不填
token	string	否	腾讯云 API 临时密钥对 Token，通过 申请扮演角色临时访问凭证 接口获取。传递此字段时意味着使用的是临时凭证，如果显式传递临时凭证，则此参数必传
timeout	number	否	调用接口的超时时间（ms），默认为 15000ms，即 15s
proxy	string	否	调用接口时使用的 http 代理 url
region	string	否	指定地域，目前支持的地域列表参考，云函数环境下默认取当前云函数环境地域

注意事项

• 服务端环境下（非云函数环境），需要传入 secretId、secretKey
• 若当前账户为子账户，请先通过主账户授权开通 QcloudTCBFullAccess(云开发全读写访问)、QcloudAccessForTCBRole(云开发对云资源的访问权限)，子账户权限设置指引

登录鉴权

manager-node 使用管理员权限，不同环境下的鉴权方式如下：

云函数环境

在云函数环境中，无需手动配置鉴权参数。

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  envId: "your-env-id"
})

Node.js 环境

在 Node.js 环境中，需要配置以下任意一种鉴权方式：

使用 secretId 和 secretKey

前往 腾讯云控制台/API密钥管理 生成 secretKey、secretId

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  envId: "your-env-id",
  secretId: "your-secret-id",
  secretKey: "your-secret-key"
})

使用临时密钥 token

通过 申请扮演角色临时访问凭证 接口获取 token

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  envId: "your-env-id",
  token: "your-token"
})

环境管理

核心概念

@cloudbase/manager-node 支持管理多个云开发环境。SDK 内部通过 EnvironmentManager 管理所有环境实例，并维护一个当前环境的概念：

• 环境实例 (Environment)：代表一个云开发环境，每个环境有独立的资源（云函数、数据库、存储等）
• 当前环境：SDK 默认操作的环境，所有资源管理 API（如 app.functions、app.database）都作用于当前环境
• 环境管理器 (EnvironmentManager)：管理多个环境实例，支持环境的添加和切换

单环境使用

大多数场景下，你只需要管理一个环境：

import CloudBase from '@cloudbase/manager-node'

// 初始化时指定 envId，该环境自动成为当前环境
const app = CloudBase.init({
  secretId: "your-secret-id",
  secretKey: "your-secret-key",
  envId: "your-env-id"
})

// 直接操作当前环境的资源
await app.functions.getFunctionDetail("test")
await app.database.listCollections()

多环境管理

当需要管理多个环境时（例如同时操作开发环境和生产环境），可以使用环境管理器：

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: "your-secret-id",
  secretKey: "your-secret-key",
  envId: "dev-env-id"  // 开发环境作为初始当前环境
})

// 获取环境管理器
const envManager = app.getEnvironmentManager()

// 添加生产环境
envManager.addEnvironment("prod-env-id")

// 获取当前环境（此时是 dev-env-id）
const currentEnv = envManager.currentEnvironment()
console.log(currentEnv.EnvId)  // 输出：dev-env-id

// 操作开发环境的云函数
await app.functions.getFunctionDetail("test")

// 切换到生产环境
envManager.switchEnv("prod-env-id")

// 现在操作的是生产环境的云函数
await app.functions.getFunctionDetail("test")

提示

• addEnvironment(envId) 不会在云开发服务中创建新环境，envId 对应的环境必须预先存在
• 如果初始化时未指定 envId，添加的第一个环境会自动成为当前环境
• 调用 switchEnv(envId) 后，所有资源管理对象（functions、database 等）都会作用于新的当前环境

环境管理 API

方法	说明	返回值
getEnvironmentManager()	获取环境管理器实例	EnvironmentManager
addEnvironment(envId)	添加环境实例到管理器中	void
currentEnvironment()	获取当前环境实例	Environment
switchEnv(envId)	切换当前环境	void

功能模块

所有资源管理能力都与当前环境关联，通过以下属性访问：

const app = CloudBase.init({
  secretId: "your-secret-id",
  secretKey: "your-secret-key",
  envId: "your-env-id"
})

// 获取当前环境下的各功能模块
app.functions      // 云函数管理
app.database       // 数据库管理
app.storage        // 文件存储管理
app.env            // 环境配置管理
app.commonService  // 通用服务管理

每个模块提供完整的资源管理能力，详见各功能模块的 API 文档。

示例代码

基础使用

import CloudBase from '@cloudbase/manager-node'

// 1. 初始化 CloudBase
const app = CloudBase.init({
  secretId: "your-secret-id",
  secretKey: "your-secret-key",
  envId: "your-env-id"
})

async function test() {
  // 2. 调用云函数管理下的 getFunction
  let result = await app.functions.getFunctionDetail("test")
  // 3. 打印结果
  console.log(result)
}

test()