鸿蒙（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

工程创建流程（详细版）https://blog.csdn.net/2403_89081261/article/details/147577688?spm=1001.2014.3001.5501

三、关键依赖配置

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-ignoreimport 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);

3. 创建云函数以及调用和传参（详细版）https://blog.csdn.net/2403_89081261/article/details/147615545?spm=1001.2014.3001.5501

注意：需在真机/模拟器测试，预览器不支持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

完整流程参考