鸿蒙（HarmonyOS 5）端云一体化开发的完整流程及关键依赖整理，涵盖工程创建、依赖配置、云函数调用等核心步骤，结合官方文档和最佳实践总结而成

​

一、环境准备

1. 开发者账号

   • 实名认证的华为开发者账号（需在AGC控制台开通项目）17。

2. 开发工具

   • 安装 DevEco Studio 5.0.0+ （需支持端云一体化模板）17。

---

二、工程创建流程

1. 创建端云一体化工程

• 步骤

  1. 在DevEco Studio中选择 "Atomic Service" 或 "Application" ，使用 "CloudDev"模板（如Empty Ability withCloudDev）17。
  2. 登录华为开发者账号，关联AGC中的项目（需提前在AGC控制台创建应用并开通云服务）711。
  3. 填写工程信息（包名需与AGC应用一致）7。

• 目录结构

  • 端侧工程 (Application)：含UI代码、agconnect-services.json配置文件。
  • 云侧工程 (CloudProgram)：含云函数、云数据库代码37

---

三、关键依赖配置

1. 端侧依赖（oh-package.json5）

"dependencies": {
  "@hw-agconnect/cloud": "^1.0.0",    // 云函数调用
  "@hw-agconnect/hmcore": "^1.0.0",   // AGC核心库
  "@hw-agconnect/auth-component": "^1.0.0", // 认证服务
  "long": "5.2.1",                    // 长整型支持（云数据库需）
  "protobufjs": "6.11.3"              // 协议缓冲区（避免版本冲突）
}

注意：若使用非模板创建项目，需手动添加；模板工程已自动集成2610。

2. 云侧依赖

• 云函数：通过npm install安装Node.js依赖（如@agconnect/database）3。
• 云数据库：需在CloudProgram/clouddb下定义数据模型（JSON Schema）11。

---

四、核心配置与初始化

1. agconnect-services.json

• 作用：包含云服务配置（如App ID、云函数/数据库权限）26。

• 位置：

  • entry/src/main/resources/rawfile/
  • AppScope/resources/rawfile/ 610。

• 获取方式：从AGC控制台下载并覆盖旧文件（修改配置后需更新）610。

2. 初始化AGC（在EntryAbility中）

import { initialize } from '@hw-agconnect/hmcore';
// @ts-ignore
import json from '../../resources/rawfile/agconnect-services.json';

export default class EntryAbility extends UIAbility {
  onCreate() {
    initialize(this.context, json); // 必须初始化
  }
}

注意：未初始化会导致云功能无法调用2610。

---

五、云函数开发与调用

1. 创建云函数

1. 右键CloudProgram/cloudfunctions → New → Cloud Function 11。
2. 示例代码（返回随机数）：

let myHandler = async (event, context, callback) => {
  callback({ code: 0, message: "Success." + Math.random() });
};
export { myHandler };

1. 部署：右键云函数 → Deploy Cloud Function 11。

2. 端侧调用云函数

import cloud from '@hw-agconnect/cloud';

const result = await cloud.callFunction({
  name: 'hello',     // 函数名
  version: '1',      // 版本或'$latest'
  params: {}         // 参数
});
console.log(result.getValue().message);

注意：需在真机/模拟器测试，预览器不支持2610。

---

六、云数据库操作

1. 定义数据模型

• 在CloudProgram/clouddb/objecttype下创建JSON文件（如book.json）定义字段11。

2. 插入初始数据

• 在CloudProgram/clouddb/dataentry下创建dataentry.json，填写初始数据11。

3. 部署数据库

• 右键clouddb → Deploy Cloud DB 11。

---

七、常见问题解决

1. protobufjs模块缺失

   • 降级到6.11.3（protobufjs@7.x移除了aspromise模块）10。

2. 真机运行报错

   • 检查签名配置（需在Project Structure → Signing Configs中启用自动签名）79。

3. 云函数返回403

   • 确保agconnect-services.json中的包名与config.json一致610

完整流程参考

​