跳到主要内容

初始化

@cloudbase/js-sdk 让您可以在 Web 端（如 PC Web 页面、微信公众平台 H5 等）使用 JavaScript 访问 Cloudbase 服务和资源。

提示

当前 @cloudbase/js-sdk 最新版本（latest）已升级至 v3，请参考v3 文档；v2 版本请使用 @cloudbase/js-sdk@v2 安装，请参考v2 文档。v1 版本不再继续升级维护，若需使用 v1 版本，请在安装时指定版本号 @cloudbase/js-sdk@v1。v1 迁移请参考迁移文档

安装​

方式一：通过包管理器引入​

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

方式二：通过 CDN 引入​

通过 CDN 引入有两种方式： 注：可前往 npm 源查看当前最新版本 https://www.npmjs.com/package/@cloudbase/js-sdk

引入全量 SDK​

<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.full.js"></script>
<script>
  const app = cloudbase.init({
    env: "your-env-id",
  });
</script>

按需引入功能模块​

<!-- 内核 -->
<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.js"></script>
<!-- 登录模块 -->
<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.auth.js"></script>
<!-- 云函数模块 -->
<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.functions.js"></script>
<!-- 云存储模块 -->
<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.storage.js"></script>
<!-- 数据库模块 -->
<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.database.js"></script>
<!-- 实时推送模块，引入前必须首先引入数据库模块 -->
<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.realtime.js"></script>
<!-- 广告上报模块-->
<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.analytics.js"></script>
<script>
  const app = cloudbase.init({
    env: "your-env-id",
  });
</script>
提示

功能模块必须在内核之后引入，并且登录模块必须引入。

最新的版本号 version 可以前往 NPM 查看。

使用​

通过包管理器安装 @cloudbase/js-sdk 之后，在项目源码中有两种引入方式：

方式一：引入全量 SDK​

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

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

方式二：按需引入功能模块​

// 内核
import cloudbase from "@cloudbase/js-sdk/app";
// 登录模块
import "@cloudbase/js-sdk/auth";
// 云函数模块
import "@cloudbase/js-sdk/functions";
// 云存储模块
import "@cloudbase/js-sdk/storage";
// 数据库模块
import "@cloudbase/js-sdk/database";
// 实时推送模块，引入前必须首先引入数据库模块
import "@cloudbase/js-sdk/realtime";
// 广告上报模块
import "@cloudbase/js-sdk/analytics";

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

功能模块必须在内核之后引入，并且登录模块必须引入。

请注意：以上代码展示的功能模块引入方式仅在浏览器环境下有效，对于非浏览器环境的 JavaScript 运行时，必须在引入功能模块后手动注册模块，代码如下：

// 内核
import cloudbase from "@cloudbase/js-sdk/app";
// 登录模块
import { registerAuth } from "@cloudbase/js-sdk/auth";
// 云函数模块
import { registerFunctions } from "@cloudbase/js-sdk/functions";
// 云存储模块
import { registerStorage } from "@cloudbase/js-sdk/storage";
// 数据库模块
import { registerDatabase } from "@cloudbase/js-sdk/database";
// 实时推送模块，引入前必须首先引入数据库模块
import { registerRealtime } from "@cloudbase/js-sdk/realtime";

// 注册功能模块
registerAuth(cloudbase);
registerFunctions(cloudbase);
registerStorage(cloudbase);
registerDatabase(cloudbase);
registerRealtime(cloudbase);

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

地域​

init 初始化时可以指定 region，默认使用上海地域（ap-shanghai），目前支持的地域列表参考。

示例： 当前有上海地域的环境 env-shanghai，广州地域的环境 env-guangzhou

则正确的初始化方式为：

// region 不填默认为上海地域，信息一致
const app = cloudbase.init({
  env: "env-shanghai",
});
// env地域 与 region 一致
const app = cloudbase.init({
  env: "env-shanghai",
  region: "ap-shanghai",
});
// env地域 与 region 一致
const app = cloudbase.init({
  env: "env-guangzhou",
  region: "ap-guangzhou",
});
提示

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

更友好的错误日志​

@cloudbase/js-sdk 在开发环境下会将调用 API 的错误信息以更友好的方式打印到控制台，如下图所示：

图中打印的错误是当前的登录类型受到函数的安全规则限制，导致没有调用函数的权限。错误信息分为两部分：

  1. 上半部分的黑色字体提示包含了后端 API 返回的错误信息以及基于此报错的一些解决方案提示；
  2. 下半部分的红色字体是经优化后的错误堆栈，由于原始错误堆栈层次太深导致 debug 非常困难，所以此处打印的错误堆栈的第一条直接定位到 SDK 源码，第二条定位到调用报错 API 的业务源码。

优化的错误提示仅在开发环境中使用，根据process.env.NODE_ENV判断是否为开发环境。此外，定位到 SDK 源码需要借助 SourceMap。

以上两点依赖构建工具的部分特性，目前仅支持 Webpack 和 Rollup。

Webpack​

在 Webpack 4+ 版本中可以配置mode选项为development，如下：

module.exports = {
  mode: "development",
};

如果是旧版本的 Webpack 需要使用DefinePlugin：

const webpack = require("webpack");

module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      "process.env.NODE_ENV": JSON.stringify("development"),
    }),
    // ...其他插件
  ],
  // ...其他配置
};

然后为 js 的编译选项加入 sourcemap 预处理，这里需要使用source-map-loader：

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        enforce: "pre",
        use: ["source-map-loader"],
      },
      // ...其他rules
    ],
  },
  // ...其他配置
};

配置完成后启动 webpack-dev-server 即可。

Rollup​

Rollup 需要使用两个插件：

配置如下：

import sourcemaps from "rollup-plugin-sourcemaps";
import replace from "rollup-plugin-replace";
export default {
  plugins: [
    sourcemaps(),
    replace({
      "process.env.NODE_ENV": JSON.stringify("development"),
    }),
    // ...其他插件
  ],
  // ...其他配置
};

配置完成使用rollup-plugin-serve启动 dev server 即可。