# @cloudbase/js-sdk 中文文档

规范地址：https://npmcn.com/package/%40cloudbase/js-sdk/

版本：3\.11\.0
npm 元数据更新时间：2026-11-02T10:01:46.027Z
中文译文更新时间：2026-11-10T02:38:00.757Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cloudbase/js-sdk
原文对照：https://npmcn.com/package/%40cloudbase/js-sdk/?lang=original
项目主页：https://github.com/TencentCloudBase/cloudbase-js-sdk#readme
源码仓库：https://github.com/TencentCloudBase/cloudbase-js-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：24.4 MB，328 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：14 个
- 首次发布：2020-06-18T03:21:01.191Z
- 最新版本发布：2026-11-02T10:01:45.834Z
- 近 30 天下载量：67073（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：474（近 12 个月 202 个）

## 中文简介

云库 javascript sdk

## 安装

```sh
npm install @cloudbase/js-sdk
```

也可以使用：`pnpm add @cloudbase/js-sdk`、`yarn add @cloudbase/js-sdk`、`bun add @cloudbase/js-sdk`

## README

## @cloudbase/js-sdk

云开发 Cloudbase JavaScript SDK。

### 安装使用

@cloudbase/js-sdk 分为两种形式：

1.  全量-包含所有云开发功能 API；
2.  分模块-各功能拆分为细粒度的模块单独提供服务。

#### 包管理器

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

引入时可选择全量引入：

```javascript
import cloudbase from '@cloudbase/js-sdk'
```

或者按需分模块引入：

```javascript
// 内核
import cloudbase from '@cloudbase/js-sdk/app'
// 登录模块
import cloudbase from '@cloudbase/js-sdk/auth'
// 函数模块
import cloudbase from '@cloudbase/js-sdk/functions'
// 云存储模块
import cloudbase from '@cloudbase/js-sdk/storage'
// 数据库模块
import cloudbase from '@cloudbase/js-sdk/database'
// 数据模型模块
import cloudbase from '@cloudbase/js-sdk/model'
```

#### 在 Node / 服务端（含 SSR）使用

在浏览器、小程序、Node.js / 服务端（含 Next.js、Nuxt 等 SSR）环境下，**直接安装 `@cloudbase/js-sdk` 即可，无需任何额外依赖，也无需在打包器中做任何配置**（例如不需要 `next.config.js` 里的 `serverExternalPackages` 或 `webpack` 兜底）。

SDK 的 Node 端部分能力依赖以下三个包，它们是**可选依赖**——仅当你在 Node 服务端**真正调用**对应能力时才需要安装：

| 能力 | 需要的可选依赖 | 安装命令 |
| --- | --- | --- |
| 自定义登录票据（`createTicket`） | `jsonwebtoken` | `npm install jsonwebtoken` |
| Node 环境请求签名 | `@cloudbase/signature-nodejs` | `npm install @cloudbase/signature-nodejs` |
| Node 环境 WebSocket（实时能力） | `ws` | `npm install ws` |

一次性安装全部：

```bash
npm install jsonwebtoken @cloudbase/signature-nodejs ws
```

> **为什么无需打包器配置**：这三个可选依赖并非在源码里以静态 `import '包名'` 或 `require('包名')`（字面量）的方式引用，而是通过内部的运行时加载工具按需加载——模块名在运行时由片段拼接得到、`require` 从宿主运行时获取。因此打包器（webpack / Next.js / Nuxt 等）在**静态分析阶段完全看不到这些模块名**，不会去解析它们，也就不会出现 `Module not found: Can't resolve 'xxx'` 报错。未安装时只有在 Node 运行时真正调用相关能力才会给出「请安装 xxx」的友好提示，纯浏览器 / 未用到这些能力的项目则完全无感。

#### CDN 引入

1.  引入全量 js 文件
    
    ```html
    <!-- 全量js文件 -->
    <script src="/cloudbase.full.js"></script>
    ```
    
2.  分模块引入
    
    ```html
    <!-- 主js文件 -->
    <script src="/cloudbase.js"></script>
    <!-- 登录模块 -->
    <script src="/cloudbase.auth.js"></script>
    <!-- 函数模块 -->
    <script src="/cloudbase.functions.js"></script>
    <!-- 云存储模块 -->
    <script src="/cloudbase.storage.js"></script>
    <!-- 数据库模块 -->
    <script src="/cloudbase.database.js"></script>
    <!-- 数据模型模块 -->
    <script src="/cloudbase.model.js"></script>
    ```
    

### 构建

构建分为两部分：

1.  构建 npm 包，产出文件分属于各模块子目录；
2.  构建 CDN 托管的 js 文件，产出文件存放于`cdnjs`目录，按版本划分

```bash
npm run build
```

## 常见问题

### @cloudbase/js-sdk 是什么？

云库 javascript sdk

### 如何安装 @cloudbase/js-sdk？

在项目目录运行 npm install @cloudbase/js-sdk，或使用 pnpm add / yarn add / bun add。

### @cloudbase/js-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cloudbase/js-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cloudbase/js-sdk 可以商用吗？

@cloudbase/js-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cloudbase/js-sdk 的下载量有多少？

根据 npm 官方下载统计，@cloudbase/js-sdk 在 2026/10/10 – 2026/11/08 这 30 天内被下载 67,073 次，日均约 2,236 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cloudbase/js-sdk 还在维护吗？

最新版本 3\.11\.0 发布于 2026/11/02（7 天前）；至今共发布 474 个版本，其中过去 12 个月发布了 202 个；首次发布于 2020/06/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。