跳到主要内容

初始化

NPM Version

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

安装 SDK​

npm install @cloudbase/manager-node -S

初始化 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"
})

初始化参数​

字段类型必填说明
envIdstring否TCB 环境 ID，在 云开发控制台 概览页面获取。不填使用默认环境，因为后续的很多接口依赖于环境，在未传递的情况下，需要通过 addEnvironment() 添加环境方可进行后续接口调用
secretIdstring否腾讯云 API 固定密钥对 secretId，前往 腾讯云控制台/API密钥管理 生成。secretId 与 secretKey 必须同时传递，在云函数内执行可不填
secretKeystring否腾讯云 API 固定密钥对 secretKey，前往 腾讯云控制台/API密钥管理 生成。secretId 与 secretKey 必须同时传递，在云函数内执行可不填
tokenstring否腾讯云 API 临时密钥对 Token，通过 申请扮演角色临时访问凭证 接口获取。传递此字段时意味着使用的是临时凭证，如果显式传递临时凭证，则此参数必传
timeoutnumber否调用接口的超时时间（ms），默认为 15000ms，即 15s
proxystring否调用接口时使用的 http 代理 url
regionstring否指定地域，目前支持的地域列表参考，云函数环境下默认取当前云函数环境地域
注意事项
  • 服务端环境下（非云函数环境），需要传入 secretId、secretKey
  • 若当前账户为子账户，请先通过主账户授权开通 QcloudTCBFullAccess(云开发全读写访问)、QcloudAccessForTCBRole(云开发对云资源的访问权限)，子账户权限设置指引

登录鉴权​

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

云函数环境​

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

import CloudBase from '@cloudbase/manager-node'

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

Node.js 环境​

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

前往 腾讯云控制台/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"
})

环境管理​

核心概念​

@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              // 环境配置管理（含自定义域名与访问路由，v5.0.0+）
app.commonService    // 通用服务管理
app.hosting          // 静态网站托管
app.cloudBaseRun     // 云托管（TCBR）管理
app.cloudAppService  // 应用部署管理（v5.0.0+）
app.log              // CLS 日志服务（v5.0.0+）
app.permission       // 权限与角色管理（v5.0.0+）
app.mysql            // MySQL 数据库管理（v5.0.0+）
app.docs             // 官方文档检索与读取（v5.0.0+）
app.aiModel          // AI 模型分组管理（v5.2.0+）

每个模块提供完整的资源管理能力，详见各功能模块的 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()