数据存储 JavaScript SDK 配置指南
获取 SDK
本指南按照应用的适用平台来介绍各自的安装与集成方式。
Web
适用于运行在浏览器、WebView 或其他应用内 HTML 平台上的应用。
安装与引用 SDK
npm
如果你的 Web 应用使用了 webpack 等前端打包工具，我们推荐使用包管理工具 npm 安装 SDK：
- 存储服务
$ npm install leancloud-storage --save
如果因为网络原因无法通过官方的 npm 站点下载，推荐通过 taobao 镜像来下载（在 npm install 后添加 --registry=https://registry.npm.taobao.org 参数）。
安装完成后，在代码中通过 require 获得 SDK 的引用：
- 存储服务
const AV = require("leancloud-storage");
const { Query, User } = AV;
CDN
以下 CDN 资源为第三方服务商提供的免费服务，无可用性保证，不推荐在生产环境中使用。
你也可以直接在页面中通过 script 标签引入我们的 SDK：
- 存储服务
<script src="//code.bdstatic.com/npm/[email protected]/dist/av-min.js"></script>
通过这种方式引入的 SDK 可以通过全局变量 AV 获得引用：
- 存储服务
const { Query, User } = AV;
Node.js
JavaScript SDK 也可以运行在 Node.js 运行环境中。如果希望在云引擎中访问我们的存储服务，请参照 云引擎 Node.js 运行环境，使用模板项目中提供的 leanengine 包接入存储服务。
注意，云引擎内部访问 API 是通过内网，所以不需要也不应该配置 API 自定义域名。 模板项目和云引擎 SDK 使用指南中的示例代码均未配置 API 自定义域名， 请勿设置 serverURL，以免变成公网访问，影响性能。
安装与引用 SDK
Node.js 中 SDK 的安装与引用也是通过包管理工具 npm，请参考 npm。
微信 / QQ 小程序
QQ 小程序兼容微信小程序的 API，因此两者使用同一个 SDK，安装与使用方法也是一样的。不过 QQ 小程序使用的 Adapters 与微信小程序不同，请前往 QQ 小程序 Adapters 下载页 下载。
手动导入文件
- 存储服务
前往 存储 SDK 下载页，下载最新版本的 av-core-min.js，移动到 libs 目录。
前往 微信小程序 Adapters 下载页，下载最新版本的 index.js，移动到 libs 目录，并将文件重命名为 leancloud-adapters-weapp.js。
在 app.js 中引用 SDK，并设置 Adapters ：
在其他文件中引用 SDK 时请将路径替换成对应的相对路径，Adapters 仅需在 app.js 中设置。
- 存储服务
const AV = require("./libs/av-core-min.js");
const adapters = require("./libs/leancloud-adapters-weapp.js");
AV.setAdapters(adapters);
WePY
如果使用 WePY 来开发小程序，可以直接通过 npm 安装和引用 SDK，具体操作步骤请参考 npm。
mpvue
如果使用 mpvue 来开发小程序，可以直接通过 npm 安装和引用 SDK，具体操作步骤请参考 npm。
Taro
如果使用 Taro 来开发小程序，通过 npm 安装 SDK 后，需要从指定路径引入小程序 SDK：
import AV from "leancloud-storage/dist/av-weapp.js";
如果使用 TypeScript 开发，可以手动把 leancloud-storage/storage.d.ts 复制到 leancloud-storage/dist/av-live-query-weapp.d.ts。
小程序插件
小程序插件引入 SDK 的方法与微信小程序一致。
微信 / QQ 小游戏
小游戏手动导入 SDK 的步骤与小程序一致，请参考 微信 / QQ 小程序 · 手动导入文件。
如果使用游戏引擎提供的开发工具开发小游戏，请参照对应的游戏引擎章节。
支付宝小程序
支付宝小程序通过 npm 安装与引用 SDK，同时由独立的 Adapters 库（@leancloud/platform-adapters-alipay）提供支持。
安装：
- 存储服务
$ npm install leancloud-storage @leancloud/platform-adapters-alipay
获得引用：
- 存储服务
const AV = require("leancloud-storage/core");
const adapters = require("@leancloud/platform-adapters-alipay");
AV.setAdapters(adapters);
百度小程序
百度小程序通过 npm 安装与引用 SDK，同时由独立的 Adapters 库（@leancloud/platform-adapters-baidu）提供支持。
安装：
- 存储服务
$ npm install leancloud-storage @leancloud/platform-adapters-baidu
获得引用：
- 存储服务
const AV = require("leancloud-storage/core");
const adapters = require("@leancloud/platform-adapters-baidu");
AV.setAdapters(adapters);
字节跳动小程序
- 存储服务
前往 存储 SDK 下载页，下载最新版本的 av-core-min.js，移动到 libs 目录。
前往 字节跳动小程序 Adapters 下载页，下载最新版本的 index.js，移动到 libs 目录，并将文件重命名为 leancloud-adapters-toutiao.js。
在 app.js 中引用 SDK，并设置 Adapters ：
在其他文件中引用 SDK 时请将路径替换成对应的相对路径，Adapters 仅需在 app.js 中设置。
- 存储服务
const AV = require("./libs/av-core-min.js");
const adapters = require("./libs/leancloud-adapters-toutiao.js");
AV.setAdapters(adapters);
CocosCreator
CocosCreator 支持直接通过 npm 安装与引用 SDK，具体操作步骤请参考 npm。
CocosCreator 项目默认没有 package.json 文件，可以在安装 SDK 前通过 npm init -y 命令创建。
如果你的 CocosCreator 项目需要发布为微信或 QQ 小游戏，需要在构建发布到小游戏之前修改 SDK 的引用路径：
- 存储服务
// SDK 应用路径变更为
- const AV = require('leancloud-storage');
+ const AV = require('leancloud-storage/dist/av-weapp-min.js');
请注意，此改动会导致其他平台的产出（包括浏览器与模拟器的预览功能）不能正常工作，因此应该只在构建发布到小游戏之前临时修改，并在发布之后修改回来。
在改动之后，CocosCreator 的控制台可能会出现 load script error，但不影响构建发布小游戏，并且构建产出在小游戏开发工具中运行也不会有异常。
LayaAir
LayaAir 支持直接通过 npm 安装与引用 SDK，具体操作步骤请参考 npm。
LayaAir 项目默认没有 package.json 文件，可以在安装 SDK 前通过 npm init -y 命令创建。
如果你的 LayaAir 项目需要发布为微信或 QQ 小游戏，需要在构建发布到小游戏之前修改 SDK 的引用路径，具体替换方法请参考 CocosCreator 章节。
同样，此改动会导致其他平台的产出（包括浏览器与模拟器的预览功能）不能正常工作，因此应该只在构建发布到小游戏之前临时修改，并在发布之后修改回来。
快应用
快应用通过 npm 安装与引用 SDK，同时由独立的 Adapters 库（@leancloud/platform-adapters-quickapp）提供支持。
安装：
- 存储服务
$ npm install leancloud-storage @leancloud/platform-adapters-quickapp --save
获得引用：
- 存储服务
const AV = require("leancloud-storage/core");
const adapters = require("@leancloud/platform-adapters-quickapp");
AV.setAdapters(adapters);
React Native
React Native 通过 npm 安装与引用 SDK，同时由独立的 Adapters 库（@leancloud/platform-adapters-react-native）提供支持。
安装：
- 存储服务
# Step 1: Install
$ yarn add leancloud-storage @leancloud/platform-adapters-react-native @react-native-community/async-storage@1
# Step 2: Link
# For React Native 0.60+
$ npx pod-install
# For React Native <= 0.59
# npx react-native link @react-native-community/async-storage
# For Expo (SDK >= 38) 无需 link
获得引用：
- 存储服务
import AV from "leancloud-storage/core";
import * as adapters from "@leancloud/platform-adapters-react-native";
AV.setAdapters(adapters);
Electron
Electron 使用包管理工具 npm 管理依赖，你可以通过以下命令安装 SDK：
- 存储服务
$ npm install leancloud-storage --save
作为浏览器脚本引入
在 index.html 中可以通过 script 标签引入 SDK：
- 存储服务
<script src="./node_modules/leancloud-storage/dist/av-min.js"></script>
作为 Node.js 模块引入
我们推荐使用 script 标签引入 SDK，该方式能满足绝大部分的需求。但是如果有以下的需求，SDK 也支持通过 require('leancloud-storage') 方法作为 Node.js 模块引入。
- 需要在 main process 中使用 SDK
- 需要使用 Node.js 的
Buffer或Stream构造AV.File
通过 Node.js require 方法引入的 SDK 与通过浏览器 script 标签引入的 SDK 是两个不同的 SDK，需要各自分别初始化，并且不能混用。
其他平台
SDK 提供了平台无关的的版本以支持其他平台。所有平台相关的 API 被抽象成了可配置的 Adapters，在目标平台引入 SDK 后还需要配置目标平台的 Adapters。假设在 npm 上存在某平台（xyz）的 adapters package（platform-adapters-xyz），需要通过以下方式配置 SDK：
- 存储服务
const AV = require("leancloud-storage/core");
const adapters = require("platform-adapters-xyz");
AV.setAdapters(adapters);
对于不支持使用 npm 管理依赖的运行环境，SDK 同时也提供了预编译好的 UMD 类型文件：
- 存储服务
https://code.bdstatic.com/npm/[email protected]/dist/av-core-min.js
开发者可以自行实现目标平台的 Adapters 来适配该平台。Adapters 的接口定义可以在 package @leancloud/adapter-types 中找到。你也可以通过关键字 platform-adapters 查找社区中其他开发者贡献的 Adapters。
初始化
无论是通过 npm 安装还是直接通过 CDN 加载，初始化的方法都是一样的。
- 存储服务
AV.init({
appId: "your-client-id",
appKey: "your-client-token",
serverURL: "https://your_server_url",
});
应用凭证
在 开发者中心 > 你的游戏 > 游戏服务 > 应用配置 可以查看应用的基本信息：
- Client ID：又称
App ID，在 SDK 初始化时用到。 - Client Token：又称
App Key，客户端对服务端的调用凭证，在 SDK 初始化时用到。 - 域名配置 > 云服务 API：又称 API 域名或 Server URL，在客户端 SDK 初始化时用到。域名配置参考下一节域名。
- Server Secret：又称
Master Key，用于在自有服务器、云引擎等受信任环境调用管理接口，具备跳过一切权限验证的超级权限。所以一定注意保密，千万不要在客户端代码中使用该凭证。
域名
使用 TDS 提供的云服务，初始化客户端 SDK 需要在 server_url 处填入 API 域名，可前往 开发者中心 > 你的游戏 > 游戏服务 > 应用配置 > 域名配置 获取 TDS 提供的 共享域名。
开启调试日志
在应用开发阶段，你可以选择开启 SDK 的调试日志（debug log）来方便追踪问题。调试日志开启后，SDK 会把网络请求、错误消息等信息输出到 IDE 的日志窗口，或是浏览器 Console 或是云引擎日志（如果在云引擎下运行 SDK）。
如果是在 Node.js 中运行，可以通过在启动应用时设置环境变量来打印调试日志（下面假设启动应用的命令是 npm start）：
- 存储服务
DEBUG=leancloud* npm start
如果是在浏览器中运行，可以通过设置 localStorage 来让日志打印到浏览器控制台：
- 存储服务
localStorage.setItem('debug', 'leancloud*');
除了在 Node.js 中使用环境变量，在浏览器中使用 localStorage 启用调试模式外，新版本的 SDK 还支持在代码中启用、停用调试模式。
- 存储服务
// 需要 SDK 版本 >= v3.14.0
const AV = require("leancloud-storage");
AV.debug.enable(); // 启用
AV.debug.disable(); // 停用
在应用发布之前，请关闭调试日志，以免暴露敏感数据。
验证
首先，确认本地网络环境是可以访问云端服务器的，可以执行以下命令：
curl "https://{{host}}/1.1/date"
{{host}} 为绑定的 API 自定义域名。
如果当前网络正常会返回当前时间：
{ "__type": "Date", "iso": "2020-10-12T06:46:56.000Z" }
然后在项目中编写如下测试代码：
const TestObject = AV.Object.extend("TestObject");
const testObject = new TestObject();
testObject.set("words", "Hello world!");
testObject.save().then((testObject) => {
console.log("保存成功。");
});
保存后运行程序。
然后打开 开发者中心 > 你的游戏 > 游戏服务 > 云服务 > 数据存储 > 结构化数据 > TestObject，如果看到数据表中出现一行「words」列的值为「Hello world!」的数据，说明 SDK 已经正确地执行了上述代码，配置完毕。
如果控制台没有发现对应的数据，请参考 问题排查。
问题排查
SDK 安装指南基于当前最新版本的 SDK 编写，所以排查问题前，请先检查下安装的 SDK 是不是最新版本。
401 Unauthorized
如果 SDK 抛出 401 异常或者查看本地网络访问日志存在：
{
"code": 401,
"error": "Unauthorized."
}
则可认定为 App ID 或者 App Key 输入有误，或者是不匹配，很多开发者同时注册了多个应用，导致拷贝粘贴的时候，用 A 应用的 App ID 匹配 B 应用的 App Key，这样就会出现服务端鉴权失败的错误。
客户端无法访问网络
客户端尤其是手机端，应用在访问网络的时候需要申请一定的权限。