初始化

在小程序端开始使用云能力前,需先调用 wx.cloud.init 方法完成云能力初始化(注意小程序需先开通云服务,开通的方法是点击工具栏左上角的 “控制台” 按钮)。因此,如果要使用云能力,通常我们在小程序初始化时即调用这个方法。

小程序端初始化

wx.cloud.init 方法的定义如下:

function init(options): void

wx.cloud.init 方法接受一个可选的 options 参数,方法没有返回值。方法只能调用一次,多次调用时只有第一次调用生效。

options 参数定义了云开发的默认配置,该配置会作为之后调用其他所有云 API 的默认配置,options 提供的可选配置如下:

字段 数据类型 必填 默认值 说明
env string | object 后续 API 调用的默认环境配置,传入字符串形式的环境 ID 可以指定所有服务的默认环境,传入对象可以分别指定各个服务的默认环境,见下方详细定义
traceUser boolean false 是否在将用户访问记录到用户管理中,在控制台中可见

env 传入参数为对象时,可以指定各个服务的默认环境,可选字段如下:

字段 数据类型 必填 默认值 说明
database string 数据库 API 默认环境配置
storage string 存储 API 默认环境配置
functions string 云函数 API 默认环境配置

注意env 设置只会决定小程序端 API 调用的云环境,并不会决定云函数中的 API 调用的环境,在云函数中需要通过 wx-server-sdkinit 方法重新设置环境。

示例代码:

wx.cloud.init({
  env: 'test-x1dzi'
})

云函数端初始化

cloud.init 方法的定义如下:

function init(options): void

cloud.init 方法接受一个可选的 options 参数,方法没有返回值。方法只能调用一次,多次调用时只有第一次调用生效。

options 参数定义了云开发的默认配置,该配置会作为之后调用其他所有云 API 的默认配置,options 提供的可选配置如下:

字段 数据类型 必填 默认值 说明
env string | object 后续 API 调用的默认环境配置,传入字符串形式的环境 ID 或传入 cloud.DYNAMIC_CURRENT_ENV 可以指定所有服务的默认环境,传入对象可以分别指定各个服务的默认环境,见下方详细定义

env 传入参数为对象时,可以指定各个服务的默认环境,可选字段如下:

字段 数据类型 必填 默认值 说明
database string default 数据库 API 默认环境配置
storage string default 存储 API 默认环境配置
functions string default 云函数 API 默认环境配置
default string 缺省时 API 默认环境配置

注意env 设置只会决定本次云函数 API 调用的云环境,并不会决定接下来其他被调云函数中的 API 调用的环境,在其他被调云函数中需要通过 init 方法重新设置环境。

建议:在设置 env 时指定 cloud.DYNAMIC_CURRENT_ENV 常量 (需 SDK v1.1.0 或以上) ,这样云函数内发起数据库请求、存储请求或调用其他云函数的时候,默认请求的云环境就是云函数当前所在的环境:

const cloud = require('wx-server-sdk')
cloud.init({
  env: cloud.DYNAMIC_CURRENT_ENV
})

exports.main = async (event) => {
  const { ENV, OPENID, APPID } = cloud.getWXContext()

  // 如果云函数所在环境为 abc,则下面的调用就会请求到 abc 环境的数据库
  const dbResult = await cloud.database().collection('test').get()

  return {
    dbResult,
    ENV,
    OPENID,
    APPID,
  }
}

注:上述代码中的 env 参数的值不能用 cloud.getWXContext().ENV 替代,因为在 exports.main 外部调用的 getWXContext() 无法获取到当前环境

API 风格

云开发的 API 风格与框架组件和 API 风格一致,但同时支持回调风格和Promise风格。在传入 API 的 Object 参数中,如果传入了 successfailcomplete 字段,则我们认为是采用回调风格,API 方法调用不返回 Promise。如果传入 API 的 Object 参数中 successfailcomplete 这三个字段都不存在,则我们认为是采用Promise风格,API 方法调用返回一个 PromisePromise resolve 的结果同传入 success 回调的参数,reject 的结果同传入 fail 的参数。

注意事项

  • 如果 init 时不传 env 参数,后续 API 调用将默认请求到第一个创建的环境,但这种方式并不总是预期的,因此这种方式已废弃,请务必明确传入 env 参数