初始化

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

安装 SDK

npm
yarn
pnpm

npm install @cloudbase/manager-node -S

yarn add @cloudbase/manager-node

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
使用临时密钥 token

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

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              // 环境配置管理（含自定义域名与访问路由，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()

安装 SDK​

初始化 SDK​

初始化参数​

登录鉴权​

云函数环境​

Node.js 环境​

环境管理​

核心概念​

单环境使用​

多环境管理​

环境管理 API​

功能模块​

示例代码​

基础使用​