初始化
@cloudbase/js-sdk 让您可以在 Web 端(如 PC Web 页面、微信公众平台 H5 等)使用 JavaScript 访问 Cloudbase 服务和资源。
提示
当前@cloudbase/js-sdk 已升级至 2.x 版本,若需使用 1.x 版本,请参考文档 以及 SDK 升级指南。
#
安装#
方式一:通过包管理器引入#npmnpm install @cloudbase/js-sdk@2.0.1-alpha.0 -S# yarnyarn add @cloudbase/js-sdk@2.0.1-alpha.0
#
方式二:通过 CDN 引入通过 CDN 引入有两种方式:
#
引入全量 SDK<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.full.js"></script><script> const app = cloudbase.init({ env: "your-env-id", clientId: "xxxx" // 应用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", clientId: "xxxx" // 应用ID })</script>
提示
功能模块必须在内核之后引入,并且登录模块必须引入。
最新的版本号 version 可以前往 NPM 查看。
#
使用通过包管理器安装 @cloudbase/js-sdk 之后,在项目源码中有两种引入方式:
#
方式一:引入全量 SDKimport cloudbase from "@cloudbase/js-sdk"
const app = cloudbase.init({ env: "your-env-id", clientId: "xxxx" // 应用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", clientId: "xxxx" // 应用ID})
#
地域init 初始化时可以指定 region,默认使用上海地域(ap-shanghai),目前支持的地域列表参考。
示例: 当前有上海地域的环境 env-shanghai,广州地域的环境 env-guangzhou
则正确的初始化方式为:
// region 不填默认为上海地域,信息一致const app = cloudbase.init({ env: "env-shanghai", clientId: "xxxx" // 应用ID})
// env地域 与 region 一致const app = cloudbase.init({ env: "env-shanghai", clientId: "xxxx", // 应用ID region: "ap-shanghai"})
// env地域 与 region 一致const app = cloudbase.init({ env: "env-guangzhou", clientId: "xxxx", // 应用ID region: "ap-guangzhou"})
提示
当前使用的环境所属地域,必须与当前指定的地域信息一致!
#
更友好的错误日志@cloudbase/js-sdk 在开发环境下会将调用 API 的错误信息以更友好的方式打印到控制台,如下图所示:
图中打印的错误是当前的登录类型受到函数的安全规则限制,导致没有调用函数的权限。错误信息分为两部分:
- 上半部分的黑色字体提示包含了后端 API 返回的错误信息以及基于此报错的一些解决方案提示;
- 下半部分的红色字体是经优化后的错误堆栈,由于原始错误堆栈层次太深导致 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 即可。
#
RollupRollup 需要使用两个插件:
- rollup-plugin-replace用来注入
process.env.NODE_ENV
- rollup-plugin-sourcemaps用来加载 sourcemap
配置如下:
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 即可。