云函数客户端API

更新时间：2026-06-26 15:12:01

本文将简单介绍在小程序/小游戏侧，如何使用 callContainer 快速调用云函数服务。

云托管服务支持单实例和多实例两种调用方式，开发者可以根据业务需求选择合适的调用方式。

单实例调用

Promise 风格

javascript

xhs.cloud.init({ envId: 'your-env-id' })
  .then(() => {
    return xhs.cloud.callContainer({
      path: '/api/user/info',
      init: {
        method: 'GET'
      }
    });
  })
  .then(({ statusCode, header, data }) => {
    console.log('调用成功');
    console.log('状态码:', statusCode);
    console.log('响应数据:', JSON.parse(data));
  })
  .catch((err) => {
    console.error('调用失败', err.errMsg);
  });

回调风格

javascript

复制代码

xhs.cloud.init({
  envId: 'your-env-id',
  success: () => {
    xhs.cloud.callContainer({
      path: '/api/user/info',
      init: {
        method: 'GET'
      },
      success: ({ statusCode, header, data }) => {
        console.log('调用成功');
        console.log('状态码:', statusCode);
        console.log('响应数据:', JSON.parse(data));
      },
      fail: (err) => {
        console.error('调用失败', err.errMsg);
      }
    });
  }
});

多实例调用

多实例调用时，

header

和

method

直接放在

callContainer

的参数中，不需要放在

init

对象中。

Promise 风格

javascript

复制代码

var c1 = new xhs.cloud.Cloud()
await c1.init({
  resourceEnv: '环境id'
})
const r = await c1.callContainer({
  path: '/xxx', // 填入业务自定义路径
  header: {
    'X-XHS-SERVICE': 'xxx', // 填入服务名称
  },
  method: 'POST',
})
console.log(r)

回调风格

javascript

复制代码

var c1 = new xhs.cloud.Cloud()

c1.init({
  resourceEnv: '环境id',
  success: () => {
    c1.callContainer({
      path: '/xxx', // 填入业务自定义路径
      header: {
        'X-XHS-SERVICE': 'xxx', // 填入服务名称
      },
      method: 'POST',
      success: ({ statusCode, header, data }) => {
        console.log('调用成功');
        console.log('状态码:', statusCode);
        console.log('响应数据:', JSON.parse(data));
      },
      fail: (err) => {
        console.error('调用失败', err.errMsg);
      }
    });
  }
});

xhs.cloud.init

初始化云环境，在使用云托管服务前必须调用。

语法

xhs.cloud.init(options)

参数说明

参数	类型	默认值	必填	说明
options	object	-	是	初始化配置

options 说明

参数	类型	默认值	必填	说明
envId	string	-	是	云环境 ID

返回值

返回一个 Promise 对象。

调用风格

Promise 风格

javascript

复制代码

xhs.cloud.init({ envId: 'your-env-id' })
  .then(() => {
    console.log('初始化成功');
  })
  .catch((err) => {
    console.error('初始化失败', err);
  });

回调风格

javascript

复制代码

xhs.cloud.init({
  envId: 'your-env-id',
  success: () => {
    console.log('初始化成功');
  },
  fail: (err) => {
    console.error('初始化失败', err);
  }
});

错误说明

错误信息	说明
初始化失败	云环境 ID 无效或网络错误

xhs.cloud.callContainer

发起一个云托管服务的调用请求。

语法

xhs.cloud.callContainer(options)

参数说明

参数	类型	默认值	必填	说明
options	object	-	是	请求配置

options 说明

参数	类型	默认值	必填	说明
path	string	-	是	服务地址，即云函数路由路径，需以 / 开头；GET 等不支持 body 的方法，参数以 query string 形式拼接在 path 上，如 /api/index?name=xyq
init	object	见init说明	否	请求配置对象
success	function	-	否	接口调用成功后的回调函数
fail	function	-	否	接口调用失败后的回调函数
complete	function	-	否	接口调用结束后的回调函数（调用成功、失败都会执行）

init 说明

参数	类型	默认值	必填	说明
method	string	POST	否	网络请求方法，支持 GET/POST/OPTIONS/PUT/DELETE/TRACE/PATCH 其中 GET/OPTIONS 不支持 body，参数需以 query string 形式拼接在 path 上
header	object	{"content-type": "application/json"}	否	请求 Header
body	object/array/string/arraybuffer	-	否	请求的参数，类型随 content-type 而定（见下方对照表）注意 GET 方法的请求不能包含 body 信息
timeout	number	120000	否	超时时间，单位为毫秒

body 与 content-type 对照

body

的类型取决于请求

header

中的

content-type

，二者需保持一致，对应关系如下：

content-type	body 类型	示例
application/json	object / array	{ "name": "xyq" }
application/x-www-form-urlencoded	string	"name=xyq&age=18"
text/plain	string	"Some Text..."
application/octet-stream	arraybuffer / string	"Hello World"

返回值

成功回调

参数为 Object 类型，属性如下：

属性名	类型	说明
statusCode	number	返回的 HTTP 状态码
header	object	返回的 HTTP Response Header
data	string/any	返回的数据（小程序侧返回的是 string，需要 JSON.parse 解析）
errMsg	string	"Cloud.callContainer:ok"

失败回调

参数为 Object 类型，属性如下：

属性名	类型	说明
errMsg	string	"Cloud.callContainer:fail " + 详细错误信息
errNo	number	错误码

代码示例

Promise 风格

javascript

复制代码

const cloud = xhs.cloud;

// 先初始化云环境
xhs.cloud.init({ envId: 'your-env-id' })
  .then(() => {
    // 调用云托管服务
    return cloud.callContainer({
      path: '/example',
      init: {
        method: 'POST',
        header: {
          "content-type": "application/json",
        },
        body: {
          example: 'example',
        },
        timeout: 120000, // ms
      }
    });
  })
  .then(({ statusCode, header, data }) => {
    console.log('调用成功');
    console.log('状态码:', statusCode);
    console.log('响应头:', header);
    console.log('响应数据:', JSON.parse(data));
  })
  .catch((err) => {
    console.error('调用失败', err.errMsg);
    console.error('错误码:', err.errNo);
  });

回调风格

javascript

复制代码

const cloud = xhs.cloud;

// 先初始化云环境
xhs.cloud.init({
  envId: 'your-env-id',
  success: () => {
    // 调用云托管服务
    cloud.callContainer({
      path: '/example',
      init: {
        method: 'POST',
        header: {
          "content-type": "application/json",
        },
        body: {
          example: 'example',
        },
        timeout: 120000, // ms
      },
      success: ({ statusCode, header, data }) => {
        console.log('调用成功');
        console.log('状态码:', statusCode);
        console.log('响应头:', header);
        console.log('响应数据:', JSON.parse(data));
      },
      fail: (err) => {
        console.error('调用失败', err.errMsg);
        console.error('错误码:', err.errNo);
      },
      complete: () => {
        console.log('调用完成');
      }
    });
  }
});

错误说明

错误信息	说明
调用失败	请求路径错误或服务不可用
请求超时	服务响应超时

错误码

错误码	错误信息
10401	internal server error
小程序：20000 小游戏：20001	invalid param
21100	network error
21102	gateway error

小程序开放平台

文档中心

云函数客户端API

单实例调用

Promise 风格

回调风格

多实例调用

Promise 风格

回调风格

xhs.cloud.init

语法

参数说明

options 说明

返回值

调用风格

Promise 风格

回调风格

错误说明

xhs.cloud.callContainer

语法

参数说明

options 说明

init 说明

body 与 content-type 对照

返回值

成功回调

失败回调

代码示例

Promise 风格

回调风格

错误说明

错误码