鸿蒙 Flutter 项目打 debug、profile、release 包时分别要检查什么

适合谁看正在给鸿蒙 Flutter 项目打包的人不清楚debug / profile / release差别的人遇到构建成功但安装或运行异常的人问题背景鸿蒙 Flutter 项目的构建不只是执行一条命令这么简单。同样是生成包不同模式关注点完全不同模式核心目标典型问题debug开发链路能跑通插件没注册、权限没声明profile接近真实运行态时序问题、系统能力不稳定release正式签名和产物签名错误、安装失败如果一开始不把这三种模式的检查点拆开后面排错会很乱。项目中的真实场景当前项目里和鸿蒙构建直接相关的文件文件层作用app/pubspec.yamlFlutter 依赖层依赖管理app/ohos/build-profile.json5应用级构建层签名、产品、构建模式app/ohos/entry/build-profile.json5entry 模块构建层模块构建目标app/ohos/entry/src/main/module.json5模块声明层Ability、权限、扩展能力app/ohos/hvigorfile.ts构建脚本层构建脚本app/ohos/entry/src/main/ets/entryability/EntryAbility.ets入口层插件注册、Ability核心实现一、构建相关文件按层分开当前项目里和打包判断直接相关的文件分属不同层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模式最应该先验证的是检查清单检查项文件说明Flutter 依赖能构建app/pubspec.yamlflutter pub get成功鸿蒙壳工程完整app/ohos/目录文件齐全entry 模块能产出app/ohos/entry/HAP 能生成插件全部注册EntryAbility.ets4 个插件都 add权限声明完整module.json5INTERNET、MICROPHONE、DLP路由跳转基本可用intent_navigation_channel.dartpageId 能映射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中间而是它更接近真实运行态同时又保留了足够的观察空间检查清单检查项说明Intent 直达链稳定EntryAbility → IntentNavigationPlugin → Flutter 路由AI 页面时序正确流式输出、工具调用、状态流转系统能力正常防窥、语音识别、TTS 在接近正式态下正常桌面卡片更新DailyRecommendFormAbility 定时更新页面退出清理TTS 停止、防窥取消profile 模式下最适合验证的场景场景为什么适合 profile冷启动参数承接接近真实启动时序语音识别全链路接近真实运行态TTS 播报 停止接近真实交互防窥状态变化接近真实环境profile 模式下的构建命令flutter build hap --profileprofile 模式下的典型问题问题可能原因排查方向语音识别失败运行态时序问题检查引擎创建时机TTS 播报没声音音频通道占用检查引擎复用逻辑防窥不触发环境条件不满足真机调试路由跳转失败pending 没消费检查_consumePending()四、打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 签名材料正确signingConfigs[1].materialstoreFile、profile、certpathproducts 签名配置正确products[0].signingConfig应该是releaseSDK 版本匹配targetSdkVersion和开发环境一致兼容版本正确compatibleSdkVersion不低于 targetSdkVersion产物命名正确output.artifactNamefood_voyagerelease 模式下的构建命令flutter build hap --releaserelease 模式下的典型问题问题可能原因排查方向构建失败签名材料路径错误检查build-profile.json5安装失败签名不匹配检查 p12 和 p7b 文件运行崩溃插件没注册回到 debug 检查权限被拒module.json5 没声明检查权限列表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 模块层 → 入口插件层 → 真机运行层三种模式的检查重点对比层debugprofilereleaseFlutter 依赖依赖能构建依赖能构建依赖能构建鸿蒙构建壳工程完整壳工程完整签名配置正确entry 模块HAP 能生成HAP 能生成HAP 能安装入口插件插件注册插件注册插件注册系统能力能调用稳定调用稳定调用路由跳转能跳稳定跳稳定跳签名debug 签名debug 签名release 签名六、debug vs profile vs release 的代码差异三种模式在代码层面没有差异但在运行时行为有差异行为debugprofilerelease日志输出完整部分最少断言检查启用启用禁用调试桥接启用启用禁用性能优化无部分完整代码混淆无无可选这解释了为什么有些问题只在 release 下出现debug/profile 下日志完整容易定位release 下日志最少问题更难发现release 下代码可能被混淆堆栈更难读关键代码位置文件构建阶段app/pubspec.yamlFlutter 依赖app/ohos/build-profile.json5签名、产品、构建模式app/ohos/entry/build-profile.json5模块构建目标app/ohos/entry/src/main/module.json5Ability、权限、扩展能力app/ohos/entry/src/main/ets/entryability/EntryAbility.ets插件注册常见坑用release模式排查最基础的插件注册或路由问题— 应该先用 debugdebug能跑就误以为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— 正式签名和产物签名配置、安装验证、权限验证先把模式和检查点对齐构建排错会简单很多。遇到问题时先问自己这是哪种模式下的问题再按层排查。