SDK 初始化

🎯 SDK 对比一览

SDK 类型	适用平台	操作对象	特点	推荐场景	文档链接
小程序 SDK	微信小程序	集合	内置SDK，无需安装	小程序直接操作数据库集合	小程序 SDK 初始化
Web SDK	Web 浏览器	数据模型、集合	轻量级，支持现代浏览器	Web 应用、H5 页面	Web SDK 初始化
Node.js SDK	Node.js 环境	数据模型、集合	服务端权限，功能完整	云函数、后台服务	Node.js SDK 初始化
HTTP API	任意平台	RESTful 接口	跨语言支持	第三方系统集成	http 文档

根据选择的 SDK 进行初始化

小程序 SDK

wxCloud

wx.cloud 为小程序自带的语法，不用安装

初始化

在小程序的 app.js 中进行初始化配置：

wx.cloud.init({
    env: 'your-env-id', // 替换为您的环境 ID
    traceUser: true,
})

参数说明

字段	数据类型	必填	默认值	说明
env	string	✅ 是	-	环境 ID，指定访问哪个环境的云资源
traceUser	boolean	❌ 否	true	是否将用户访问记录到用户管理中，便于在控制台查看

集合操作示例

wx.cloud.init({
    env: 'your-env-id', // 替换为您的环境 ID
    traceUser: true,
})

// 获取数据库实例（用于集合操作）
const db = wx.cloud.database()

// 根据文档 ID 查询单条记录
const result = await db.collection('todos')
    .doc('docId')
    .get()

console.log('查询结果:', result.data)

Web SDK

JS-SDK

CloudBase js-sdk 是专为 Web 浏览器环境设计的轻量级 SDK，支持数据模型和集合两种操作方式。

安装

方式一：CDN 引入

<!-- 在 HTML 页面中直接引入 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/2.17.3/cloudbase.full.js"></script>

方式二：npm 安装

npm install @cloudbase/js-sdk --save

初始化

// CDN 引入方式：直接使用全局变量 cloudbase

// npm 引入方式
import cloudbase from "@cloudbase/js-sdk"

// 初始化应用
const app = cloudbase.init({
    env: "your-env-id" // 替换为您的环境 ID
})

// 获取数据模型实例
const models = app.models

// 获取数据库实例（用于集合操作）
const db = app.database()

认证配置

// 如果需要用户认证
const auth = app.auth()

// 匿名登录
await auth.signInAnonymously()

// 手机号登录
await auth.signIn({
    username: "+86 13800000000",
    password: "your password",
});

数据模型操作示例

import cloudbase from "@cloudbase/js-sdk"

// 初始化应用
const app = cloudbase.init({
    env: "your-env-id" // 替换为您的环境 ID
})

// 获取数据模型实例
const models = app.models

// 根据 ID 查询单条记录
const todo = await models.todo.get({
    filter: {
        where: {
            _id: {
                $eq: "todo-id-123"
            }
        }
    }
})

console.log('查询结果:', todo.records[0])

集合操作示例

import cloudbase from "@cloudbase/js-sdk"

// 初始化应用
const app = cloudbase.init({
    env: "your-env-id" // 替换为您的环境 ID
})

// 获取数据库实例（用于集合操作）
const db = app.database()

// 根据文档 ID 查询单条记录
const result = await db.collection('todos')
    .doc('docId')
    .get()

console.log('查询结果:', result.data)

Node.js SDK

Node-SDK

CloudBase node-sdk 是专为 Node.js 环境设计的服务端 SDK，具有管理员权限，支持完整的数据库功能。

安装

npm install @cloudbase/node-sdk --save

初始化

import cloudbase from "@cloudbase/node-sdk"

// 云函数环境下需要用require方式加载node-sdk
// const cloudbase = require('@cloudbase/node-sdk')

// 初始化应用
const app = cloudbase.init({
    env: "your-env-id" // 替换为您的环境 ID
})

// 获取数据模型实例
const models = app.models

// 获取数据库实例（用于集合操作）
const db = app.database()

认证配置

// 服务端 SDK 具有管理员权限，无需额外认证
// 但可以设置自定义用户上下文
const app = cloudbase.init({
    env: "your-env-id",
    credentials: {
        // 使用服务账号密钥（可选）
        private_key_id: "key-id",
        private_key: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
        client_email: "service-account@example.com"
    }
})

数据模型操作示例

import cloudbase from "@cloudbase/node-sdk"

// 云函数环境下需要用require方式加载node-sdk
// const cloudbase = require('@cloudbase/node-sdk')

// 初始化应用
const app = cloudbase.init({
    env: "your-env-id" // 替换为您的环境 ID
})

// 获取数据模型实例
const models = app.models

// 根据 ID 查询单条记录
const todo = await models.todo.get({
    filter: {
        where: {
            _id: {
                $eq: "todo-id-123"
            }
        }
    }
})

console.log('查询结果:', todo.records[0])

集合操作示例

import cloudbase from "@cloudbase/node-sdk"

// 云函数环境下需要用require方式加载node-sdk
// const cloudbase = require('@cloudbase/node-sdk')

// 初始化应用
const app = cloudbase.init({
    env: "your-env-id" // 替换为您的环境 ID
})

// 获取数据库实例（用于集合操作）
const db = app.database()

// 根据文档 ID 查询单条记录
const result = await db.collection('todos')
    .doc('docId')
    .get()

console.log('查询结果:', result.data)

🚀 下一步

接下来根据 SDK提供的 数据库实例或数据模型实例，进行数据操作

相关文档

• 集合操作指南
• 数据模型操作指南