鸿蒙 uni-app x callFunction 调用指南

鸿蒙专家

在鸿蒙端使用 uni-app x 开发时，登录、数据查询、文件上传、支付回调等需要服务端逻辑的功能，通常交给云函数。uniCloud 是 DCloud 提供的 Serverless 云服务，开发者不用自建服务器、买域名、做运维，写云函数上传后由客户端直接调用，对个人开发者和小团队比较友好。客户端入口是 uniCloud.callFunction，HarmonyOS 4.61 版本开始支持；鸿蒙平台与 Android 端一样，支持阿里云、腾讯云、支付宝云。鸿蒙平台使用前，需要在 HBuilderX 中右键项目目录，关联 uniCloud 服务空间；云服务商可选阿里云、腾讯云、支付宝云，功能差别不大，阿里云文档最全。

API 签名如下：

2. uniCloud.callFunction<T>(options: UniCloudCallFunctionOptions): Promise<UniCloudCallFunctionResult<T>>

复制代码

从 4.13 版本起支持泛型。传入泛型后，res.result 会得到明确类型；不传泛型时，返回类型为 Promise<UniCloudCallFunctionResult<UTSJSONObject>>。options 中常见字段包括 name、data、secretType；secretType 用于加密类型，设置为 'both' 表示请求和响应都加密。这个泛型能力对鸿蒙端类型安全有直接帮助，可以减少手写类型转换。

基础调用：定义 hello 云函数，客户端传 name，云函数返回 message。

2. uniCloud.callFunction({
3.   name: 'hello',
4.   data: { name: 'uni-app x' }
5. } as UniCloudCallFunctionOptions).then((res) => {
6.   console.log('云函数返回:', res.result)
7. }).catch((err) => {
8.   console.error('调用失败:', err)
9. })

复制代码

云函数侧：

2. // cloudfunctions/hello/index.js
3. 'use strict';
4. exports.main = async (event, context) => {
5.   return {
6.     errCode: 0,
7.     errMsg: '',
8.     message: 'Hello ' + event.name
9.   }
10. }

复制代码

如果希望类型更安全，可以定义返回类型并使用泛型：

2. type HelloResult = {
3.   errCode: number
4.   errMsg: string
5.   message: string
6. }
7. uniCloud.callFunction<HelloResult>({
8.   name: 'hello',
9.   data: { name: 'uni-app x' }
10. } as UniCloudCallFunctionOptions).then((res) => {
11.   const result = res.result
12.   console.log(result.message)
13. })

复制代码

这样 result.message 可以直接访问，不需要类型转换。

登录场景可把 token、userId、nickname 放进 LoginResult。调用成功后，用 uni.setStorageSync 保存 token、userId、nickname；失败时用 result.errMsg 提示。查询场景把 list 定义为 Array<UTSJSONObject>，total 为 number；云函数中用 uniCloud.database() 获取 collection('articles')，通过 where 过滤 status，count 统计总数，再用 skip、limit、orderBy 取分页数据。提交场景返回 id，云函数用 collection('articles').add 写入 title、content、createTime 和 status: 'active'。这些模式覆盖了鸿蒙端 uni-app x 常见的云函数交互。

敏感数据调用时设置 secretType: 'both'：

2. uniCloud.callFunction({
3.   name: 'process-sensitive',
4.   data: { data: sensitiveData },
5.   secretType: 'both'
6. } as UniCloudCallFunctionOptions)

复制代码

错误处理建议同时处理业务错误和网络异常。业务错误可依据 errCode 分支：0 成功，10001 参数错误，10002 未登录，10003 无权限，其他走 errMsg 或未知错误；catch 中提示网络错误或云函数异常，并让用户重试。

和鸿蒙原生对接 Cloud 服务相比，uniCloud.callFunction 省去了购买服务器、配置域名和 HTTPS、维护服务端等步骤。鸿蒙原生写法通常要引入 @kit.NetworkKit，自己拼 HTTP 请求并维护服务端；而在 uni-app x 中，写云函数并上传后即可调用。整体取舍是：个人开发者和小团队优先用 uniCloud 降低运维成本；鸿蒙平台适配的重点是确认 HarmonyOS 4.61 以上支持 callFunction、在 HBuilderX 关联服务空间、选择阿里云/腾讯云/支付宝云，并在调用侧用好泛型、加密和错误码分支。

热心网友2

感谢分享，这篇把鸿蒙端 uni-app x 调用云函数的流程讲得挺清楚的。从 HBuilderX 关联服务空间、选择云服务商，到 callFunction 的基础调用、泛型类型安全、secretType 加密和错误码分支，基本把常见场景都覆盖了。尤其是登录、查询、提交这几个例子很实用，对刚开始在鸿蒙上接 uniCloud 的人很有参考价值。我自己的话会先把 hello 示例跑通，再按业务把返回类型定义好，这样 res.result 用起来省心很多。错误处理也确实不能只 catch 网络异常，业务 errCode 分支最好也一并加上。

热心网友2

看完这篇对鸿蒙端 uniCloud.callFunction 的梳理，感觉很实用。之前只知道 uni-app x 能写鸿蒙，没想到云函数这块从 HarmonyOS 4.61 开始就支持了，而且阿里云、腾讯云、支付宝云都能接。楼主把 HBuilderX 里关联服务空间、基础调用、泛型、secretType: 'both' 和错误码分支串在一起，思路很清晰。泛型那段尤其有帮助，不传泛型时 result 是 UTSJSONObject，传了 HelloResult 后 result.message 直接可访问，确实能少写类型转换。登录保存 token、userId、nickname，查询用 list 和 total 分页，提交返回 id，这几个场景也很贴近实际。想请教一下：如果项目里云函数返回结构都按 errCode、errMsg 统一，10001、10002、10003 这类业务码是不是最好在云函数侧就约定好？另外 secretType: 'both' 对登录 token 这种敏感数据是否建议默认开启？感谢分享，先收藏按这个流程试一遍。

热心网友3

感谢分享，这份鸿蒙 uni-app x 调用云函数的指南挺清晰的。泛型那段很实用，传了 HelloResult 之后 result.message 能直接访问，确实比默认 UTSJSONObject 省心；secretType 设为 both 做请求和响应加密，敏感数据场景可以直接参考。错误码按 0、10001、10002、10003 分支处理，再配合 catch 处理网络异常，思路很完整。按帖子里说的，鸿蒙端先确认 HarmonyOS 4.61 以上、在 HBuilderX 关联服务空间、选好阿里云腾讯云或支付宝云，然后登录、查询、提交这几个模式基本能覆盖常见云函数交互。对个人开发者和小团队来说，不用自建服务器、买域名和做运维，确实省事，后面项目里可以照着试试。