import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

# 初始化

[![NPM Version](https://img.shields.io/npm/v/@cloudbase/js-sdk/latest)](https://www.npmjs.com/package/@cloudbase/js-sdk) ![Node Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)

**@cloudbase/js-sdk** 是一个跨端 JavaScript SDK，支持在 **Web 浏览器**、**Node.js 服务端**（云函数、云托管、自建服务器等）、微信小程序、React Native 等多种运行环境中统一使用 JavaScript 访问 Cloudbase 服务和资源。

:::info 提示
当前 `@cloudbase/js-sdk` 最新版本为 v3，该版本完全兼容 v2 版本，并与 [HTTP API](../../../http-api/basic/overview) 全面对齐。自 v3.1 起已内置 Node.js 适配器，无需额外安装 [`@cloudbase/node-sdk`](../server/node-sdk/initialization)。

若需使用 v2 版本，请参考[v2 文档](../webv2/initialization)
:::

::::tip 传统模式初始化
当前文档适用于 **PG 模式** 环境，如果你使用的是传统模式，请参考 [初始化（传统模式）](../webv3/initialization)。
::::

## 快速上手 {#quick-start}

只需 3 步即可开始使用云开发：

<Tabs groupId="runtime">
<TabItem value="web" label="Web 端" default>

```bash
npm install @cloudbase/js-sdk -S
```

```js
import cloudbase from "@cloudbase/js-sdk";

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

// 开始使用云开发能力
const db = app.database();
const result = await db.collection("todos").get();
```

:::tip 获取 Publishable Key
前往 [云开发平台 / API Key 配置](https://tcb.cloud.tencent.com/dev#/env/apikey) 生成。Web 端推荐使用 Publishable Key 鉴权，无需额外登录步骤。
:::

</TabItem>
<TabItem value="nodejs" label="Node.js 端">

```bash
npm install @cloudbase/js-sdk @cloudbase/signature-nodejs -S
```

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

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

// 在云函数/云托管中，SDK 自动读取环境鉴权信息
const db = app.database();
const result = await db.collection("todos").get();
```

:::tip 提示
在云函数或云托管环境中，SDK 会自动从环境变量读取鉴权信息，无需手动配置密钥。
:::

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

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

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

</TabItem>
</Tabs>

---

## 安装 SDK {#install}

<Tabs>
<TabItem value="npm" label="包管理器" default>

```bash
# npm
npm install @cloudbase/js-sdk -S

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

**全量引入：**

```js
import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env-id",
  region: "ap-shanghai", // 不传默认为上海地域
});
```

**按需引入（减少包大小）：**

```js
// 内核（必须）
import cloudbase from "@cloudbase/js-sdk/app";
// 登录模块
import { registerAuth } from "@cloudbase/js-sdk/auth";
// 数据库模块
import { registerDatabase } from "@cloudbase/js-sdk/database";
// 云函数模块
import { registerFunctions } from "@cloudbase/js-sdk/functions";
// 云存储模块
import { registerStorage } from "@cloudbase/js-sdk/storage";
// 数据模型模块
import { registerModel } from "@cloudbase/js-sdk/model";
// 实时推送模块（需先注册数据库模块）
import { registerRealtime } from "@cloudbase/js-sdk/realtime";
// AI 模块
import { registerAi } from "@cloudbase/js-sdk/ai";
// 云托管模块
import { registerCloudrun } from "@cloudbase/js-sdk/cloudrun";
// MySQL 模块
import { registerMysql } from "@cloudbase/js-sdk/mysql";

// 注册所需模块
registerAuth(cloudbase);
registerDatabase(cloudbase);
// ... 其他需要的模块

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

// 使用对应功能
const auth = app.auth;
const db = app.database();
```

| 模块名   | 包名                          | 注册函数            |
| -------- | ----------------------------- | ------------------- |
| 内核     | `@cloudbase/js-sdk/app`       | -                   |
| 登录     | `@cloudbase/js-sdk/auth`      | `registerAuth`      |
| 数据库   | `@cloudbase/js-sdk/database`  | `registerDatabase`  |
| 云函数   | `@cloudbase/js-sdk/functions` | `registerFunctions` |
| 云存储   | `@cloudbase/js-sdk/storage`   | `registerStorage`   |
| 数据模型 | `@cloudbase/js-sdk/model`     | `registerModel`     |
| 实时推送 | `@cloudbase/js-sdk/realtime`  | `registerRealtime`  |
| AI       | `@cloudbase/js-sdk/ai`        | `registerAi`        |
| 云托管   | `@cloudbase/js-sdk/cloudrun`  | `registerCloudrun`  |
| MySQL    | `@cloudbase/js-sdk/mysql`     | `registerMysql`     |

:::tip 提示

- 内核 `@cloudbase/js-sdk/app` 必须引入
- 实时推送模块依赖数据库模块，需先注册数据库
- 按需引入可有效减少最终包大小，建议生产环境使用
  :::

</TabItem>
<TabItem value="nodejs" label="Node.js 服务端">

```bash
# npm
npm install @cloudbase/js-sdk -S

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

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

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

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

**初始化 SDK**

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

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

</TabItem>
<TabItem value="cdn-full" label="CDN 全量引入">

:::info 提示
`3.x.x` 表示使用最新版本，你可以设置为固定版本
:::

```html
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.full.js"></script>
<script>
  const app = cloudbase.init({
    env: "your-env-id", // 替换为您的环境id
    region: "ap-shanghai", // 不传默认为上海地域
  });
</script>
```

</TabItem>
<TabItem value="cdn-modules" label="CDN 按需引入">

:::info 提示
`3.x.x` 表示使用最新版本，你可以设置为固定版本
:::

```html
<!-- 内核 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.js"></script>
<!-- 登录模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.auth.js"></script>
<!-- 数据库模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.database.js"></script>
<!-- 数据模型模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.model.js"></script>
<!-- 云函数模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.functions.js"></script>
<!-- 云存储模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.storage.js"></script>
<!-- 实时推送模块，引入前必须首先引入数据库模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.realtime.js"></script>
<!-- AI模块 -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.ai.js"></script>
<script>
  // 注册功能模块
  registerAuth(cloudbase);
  registerDatabase(cloudbase);
  registerModel(cloudbase);
  registerFunctions(cloudbase);
  registerStorage(cloudbase);
  registerRealtime(cloudbase);
  registerAi(cloudbase);

  const app = cloudbase.init({
    env: "your-env-id", // 替换为您的环境id
    region: "ap-shanghai", // 不传默认为上海地域
  });
</script>
```

:::tip 注意
功能模块必须在内核之后引入，并且登录模块必须引入
:::

</TabItem>
</Tabs>

最新的版本号 version 可以前往 [NPM](https://www.npmjs.com/package/@cloudbase/js-sdk) 查看。

---

## 初始化参数 {#init-params}

### 通用参数 {#common-params}

| 字段        | 类型     | 必填 | 默认值        | 说明                                                        |
| ----------- | -------- | ---- | ------------- | ----------------------------------------------------------- |
| `env`       | `string` | 是   | -             | TCB 环境 ID。Node.js 云函数环境下不传则使用当前环境 ID      |
| `region`    | `string` | 否   | `ap-shanghai` | 地域：`ap-shanghai`（默认）、`ap-guangzhou`、`ap-singapore` |
| `lang`      | `string` | 否   | `zh-CN`       | 指定语言：`zh-CN`（默认）、`en-US`                          |
| `accessKey` | `string` | 否   | -             | Cloudbase API Key / Publishable Key，用于鉴权               |
| `timeout`   | `number` | 否   | `15000`       | 请求超时时间（ms）                                          |

:::warning 注意
当前使用的环境所属地域，必须与当前指定的地域信息一致！
:::

### Node.js 端专属参数 {#nodejs-params}

:::tip Node.js 端
以下参数仅在 Node.js 环境中有效。
:::

| 字段          | 类型     | 必填 | 说明                                                                                                                                                                                                                      |
| ------------- | -------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `secretId`    | `string` | 否   | 腾讯云 API 密钥对，前往 [腾讯云控制台/API 密钥管理](https://console.cloud.tencent.com/cam/capi) 生成。也可通过环境变量 `TENCENTCLOUD_SECRETID` 配置                                                                       |
| `secretKey`   | `string` | 否   | 腾讯云 API 密钥对。也可通过环境变量 `TENCENTCLOUD_SECRETKEY` 配置                                                                                                                                                         |
| `credentials` | `object` | 否   | 自定义登录私钥，包含 `private_key`、`private_key_id`、`env_id`，用于 `createTicket` 签发登录凭据。前往 [云开发平台/身份认证/登录方式](https://tcb.cloud.tencent.com/dev?#/identity/login-manage) 的「自定义登录」下载私钥 |
| `context`     | `object` | 否   | 函数型云托管入口函数的 `context` 参数，用于免签名调用                                                                                                                                                                     |

### SYMBOL_CURRENT_ENV {#symbol-current-env}

```typescript
cloudbase.SYMBOL_CURRENT_ENV;
```

初始化时使用该字段，可指定请求当前云函数或云托管的环境。**仅在云函数或云托管环境中生效**。

:::info 注意
在云函数或云托管中，如在初始化 `init({})` 未指定 `env` 参数，则默认使用当前环境 ID，不再使用云开发默认环境。如需要使用云开发默认环境，可以指定 `init({env: tcb.SYMBOL_DEFAULT_ENV})`。
:::

```js
import cloudbase from "@cloudbase/js-sdk";

// 取当前云函数的环境初始化
const app = cloudbase.init({ env: cloudbase.SYMBOL_CURRENT_ENV });

exports.main = async (event, context) => {
  // 业务逻辑
};
```

---

## 登录鉴权 {#login-authentication}

初始化后需要完成鉴权才能使用云开发能力。Web 端和 Node.js 端鉴权方式不同：

### Web 端登录 {#web-login}

Web 端使用 **C 端** 用户权限，支持以下登录方式：

| 方式            | 适用场景               | 是否需要登录交互 |
| --------------- | ---------------------- | ---------------- |
| Publishable Key | 公开资源访问，最简方式 | ❌ 无需登录      |
| 匿名登录        | 无需注册即可使用       | ❌ 无需登录      |
| 账号密码登录    | 需要用户身份识别       | ✅ 需要          |

<Tabs>
<TabItem value="publishable-key" label="Publishable Key（推荐）" default>

Publishable Key 可以安全暴露在浏览器中，用于请求公开访问的资源，无需额外登录步骤。详细介绍请 [参考文档说明](./api-key#publishable-key-and-login-authentication)。

**获取方式：** 前往 [云开发平台 / API Key 配置](https://tcb.cloud.tencent.com/dev#/env/apikey) 生成。

```js
const app = cloudbase.init({
  env: "your-env-id",
  accessKey: "your-publishable-key", // 填入生成的 Publishable Key
});

// 无需额外登录，直接使用
const db = app.database();
```

:::warning 注意
Publishable Key 只能生成一次，并且是长期有效的、不能删除的，请妥善保管
:::

</TabItem>
<TabItem value="anonymous" label="匿名登录">

详情请参考：[匿名登录](./authentication#signinanonymously)

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

const { data, error } = await app.auth.signInAnonymously();
```

</TabItem>
<TabItem value="account" label="账号登录">

详情请参考：[账号登录](./authentication#signinwithpassword)

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

const { data, error } = await app.auth.signInWithPassword({
  username: "your username",
  password: "your password",
});
```

</TabItem>
</Tabs>

### Node.js 端鉴权 {#nodejs-authentication}

:::tip Node.js 端
服务端支持多种鉴权方式访问云开发资源（任选其一）。
:::

| 鉴权方式                      | 说明                                                             | 适用场景       |
| ----------------------------- | ---------------------------------------------------------------- | -------------- |
| 默认鉴权（云函数/云托管环境） | 无需传入参数，自动从环境变量读取密钥信息                         | 云函数、云托管 |
| API Key                       | 将服务端 API Key 配置到环境变量 `CLOUDBASE_APIKEY`，SDK 自动读取 | 自建服务器     |
| Publishable Key               | 在 `init` 中传入 `accessKey`，使用匿名角色身份访问               | 公开资源访问   |
| `secretId` + `secretKey`      | 在 `init` 中显式传入腾讯云 API 密钥对                            | 自建服务器     |
| `context`                     | 云托管场景，通过入口函数 `context` 参数实现免签名调用            | 函数型云托管   |

<Tabs>
<TabItem value="default" label="云函数环境（默认鉴权）" default>

在云函数环境中，SDK 会自动从环境变量中读取鉴权信息，此鉴权信息为**临时访问凭证**，**无需手动配置**。

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

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

exports.main = async (event, context) => {
  // 直接使用各项云开发能力
};
```

</TabItem>
<TabItem value="cloudrun" label="云托管环境">

在函数型云托管环境中，通过传入 `context` 参数实现免签名调用。

> 💡 注意：如果传入了 `context` 参数但没有 `env` 参数，则会使用 `context` 中的 `envID` 参数作为环境 ID。

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

exports.main = async (event, context) => {
  const app = cloudbase.init({
    context,
  });
  // 使用各项云开发能力
};
```

</TabItem>
<TabItem value="accessKey" label="Publishable Key">

Publishable Key 详细介绍请 [参考文档说明](./api-key#publishable-key-and-login-authentication) 。

- **用户权限**：匿名用户权限
- **有效期**：长期有效
- **获取方式**：通过[云开发平台/ApiKey 管理](https://tcb.cloud.tencent.com/dev?#/identity/token-management)获取

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

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

</TabItem>
<TabItem value="secretKey" label="secretId + secretKey">

前往 [腾讯云控制台/API 密钥管理](https://console.cloud.tencent.com/cam/capi) 生成密钥对。

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

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

</TabItem>
<TabItem value="apiKey" label="API Key">

可以通过环境变量 `CLOUDBASE_APIKEY` 配置，在云函数中开启 `API key设置`，添加 `CLOUDBASE_APIKEY`，SDK 自动读取。

<img
  src="https://qcloudimg.tencent-cloud.cn/raw/7a7ee8d929cbb9592519666806ee0a08.png"
  width="700"
  height="auto"
/>

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

// 无需显式传入，SDK 自动从环境变量读取
const app = cloudbase.init({
  env: "your-env-id",
});
```

</TabItem>
</Tabs>

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