企业官网建设流程全解析

适合谁看

• 正在给鸿蒙 Flutter 项目打包的人

• 不清楚debug / profile / release差别的人

• 遇到构建成功但安装或运行异常的人

问题背景

鸿蒙 Flutter 项目的构建，不只是执行一条命令这么简单。同样是生成包，不同模式关注点完全不同：

如果一开始不把这三种模式的检查点拆开，后面排错会很乱。

项目中的真实场景

当前项目里和鸿蒙构建直接相关的文件：

核心实现

一、构建相关文件按层分开

当前项目里，和打包判断直接相关的文件分属不同层：

Flutter 依赖层 └─ app/pubspec.yaml 鸿蒙构建层 ├─ app/ohos/build-profile.json5 ← 签名、产品、构建模式 └─ app/ohos/entry/build-profile.json5 ← 模块构建目标 模块声明层 └─ app/ohos/entry/src/main/module.json5 ← Ability、权限、扩展能力 构建脚本层 ├─ app/ohos/hvigorfile.ts └─ app/ohos/entry/hvigorfile.ts 入口与插件注册层 └─ app/ohos/entry/src/main/ets/entryability/EntryAbility.ets

只要先把这几层分清，后面就不会把"依赖问题""签名问题""入口问题"混成一类。

二、打debug包时——先确认"开发链路"是否成立

debug模式最应该先验证的是：

检查清单：

debug 模式下的典型检查：

// EntryAbility.ets - 检查插件是否全部注册 configureFlutterEngine(flutterEngine: FlutterEngine) { super.configureFlutterEngine(flutterEngine) GeneratedPluginRegistrant.registerWith(flutterEngine) flutterEngine.getPlugins()?.add(new SpeechRecognitionPlugin()) flutterEngine.getPlugins()?.add(new TextToSpeechPlugin()) flutterEngine.getPlugins()?.add(new IntentNavigationPlugin()) flutterEngine.getPlugins()?.add(new AntiPeepProtectionPlugin()) }

// module.json5 - 检查权限声明 "requestPermissions": [ {"name": "ohos.permission.INTERNET"}, {"name": "ohos.permission.MICROPHONE", "reason": "..."}, {"name": "ohos.permission.DLP_GET_HIDE_STATUS", "reason": "..."} ]

debug 模式下的日志：

# 构建成功 flutter build hap --debug # 安装成功 hdc install entry-debug.hap # 运行正常 # 检查 EntryAbility 是否启动 # 检查插件是否注册 # 检查路由是否跳转

如果 debug 都没跑通，不要急着用 release 排问题。因为那样很容易把"插件没注册"误判成"签名错了"。

三、打profile包时——把注意力切到"运行态稳定性"

profile模式的价值，不是简单介于debug和release中间，而是：

• 它更接近真实运行态

• 同时又保留了足够的观察空间

检查清单：

profile 模式下最适合验证的场景：

profile 模式下的构建命令：

flutter build hap --profile

profile 模式下的典型问题：

四、打release包时——重点已经变成"正式产物链"

到了release，最值得检查的往往已经不是页面代码，而是构建配置本身。

当前build-profile.json5的签名配置：

{ "app": { "signingConfigs": [ { "name": "default", "type": "HarmonyOS", "material": { "storeFile": "/path/to/ohos_debug.p12", "keyAlias": "ohos_debug", "signAlg": "SHA256withECDSA", "profile": "/path/to/foodVoyage_debugDebug.p7b", "certpath": "/path/to/ohos_debug_cert.cer" } }, { "name": "release", "type": "HarmonyOS", "material": { "storeFile": "/path/to/ohos_release.p12", "keyAlias": "ohos_release", "signAlg": "SHA256withECDSA", "profile": "/path/to/foodVoyage_releaseRelease.p7b", "certpath": "/path/to/ohos_cert.cer" } } ], "products": [ { "name": "default", "signingConfig": "release", "runtimeOS": "HarmonyOS", "targetSdkVersion": "6.1.0(23)", "compatibleSdkVersion": "6.1.0(23)" } ] } }

检查清单：

release 模式下的构建命令：

flutter build hap --release

release 模式下的典型问题：

release 模式下的安装验证：

# 安装 hdc install entry-release.hap # 验证安装成功 hdc shell bm dump -a # 验证 Ability 注册 hdc shell aa dump -a # 验证权限 hdc shell hidumper -s 1302

五、三种模式都要看，但顺序不能乱

更稳的排查顺序：

debug → profile → release 每一层再按： Flutter 依赖层 → 鸿蒙构建层 → entry 模块层 → 入口插件层 → 真机运行层

三种模式的检查重点对比：

六、debug vs profile vs release 的代码差异

三种模式在代码层面没有差异，但在运行时行为有差异：

这解释了为什么有些问题只在 release 下出现：

• debug/profile 下日志完整，容易定位

• release 下日志最少，问题更难发现

• release 下代码可能被混淆，堆栈更难读

关键代码位置

常见坑

• 用release模式排查最基础的插件注册或路由问题— 应该先用 debug

• debug能跑就误以为profile、release一定没问题— 三种模式检查重点不同

• 不区分"构建失败""安装失败""运行异常"— 三种问题的排查方向不同

• 只盯 Flutter 命令，不回头看build-profile.json5— 签名配置在鸿蒙侧

• 只看是否生成包，不看包安装后 Ability、权限和通道是否仍然正常— 安装后还要验证

• release 签名材料路径错误— 检查 p12、p7b、cer 文件路径

• products 的 signingConfig 没改成 release— 默认可能是 debug 签名

可复用模板

三种模式检查模板

debug：先看工程能不能跑起来 □ Flutter 依赖构建成功 □ 鸿蒙壳工程完整 □ entry 模块能生成 HAP □ 插件全部注册 □ 权限声明完整 □ 路由跳转基本可用 profile：再看运行态链路是否稳定 □ Intent 直达链稳定 □ AI 页面时序正确 □ 系统能力正常 □ 桌面卡片更新 □ 页面退出清理 release：最后看正式签名、正式产物和安装链 □ release 签名材料正确 □ products signingConfig 正确 □ SDK 版本匹配 □ HAP 能安装 □ 安装后 Ability 正常 □ 安装后权限正常 □ 安装后通道正常

构建排查顺序模板

每次都按： Flutter 依赖层 → 鸿蒙构建层 → entry 模块层 → 入口插件层 → 真机运行层 遇到问题时问自己： □ 这是构建问题还是运行问题？ □ 这是 Flutter 侧问题还是鸿蒙侧问题？ □ 这是 debug 专有问题还是三种模式都有？ □ 这是代码问题还是配置问题？

release 签名检查模板

检查 build-profile.json5： □ signingConfigs[1] 是否是 release 签名？ □ storeFile 路径是否正确？ □ profile 路径是否正确？ □ certpath 路径是否正确？ □ products[0].signingConfig 是否指向 release？ □ targetSdkVersion 和 compatibleSdkVersion 是否匹配？

本篇总结

debug、profile、release三种模式不是换个名字而已。对鸿蒙 Flutter 项目来说，它们分别对应三种不同检查目标：

• debug— 开发链路能跑通（插件、权限、路由）

• profile— 运行态链路稳定（时序、系统能力、状态管理）

• release— 正式签名和产物（签名配置、安装验证、权限验证）

先把模式和检查点对齐，构建排错会简单很多。遇到问题时，先问自己"这是哪种模式下的问题"，再按层排查。