适合谁看

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

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

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

问题背景

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

模式	核心目标	典型问题
debug	开发链路能跑通	插件没注册、权限没声明
profile	接近真实运行态	时序问题、系统能力不稳定
release	正式签名和产物	签名错误、安装失败

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

项目中的真实场景

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

文件	层	作用
app/pubspec.yaml	Flutter 依赖层	依赖管理
app/ohos/build-profile.json5	应用级构建层	签名、产品、构建模式
app/ohos/entry/build-profile.json5	entry 模块构建层	模块构建目标
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.yaml	flutter pub get 成功
鸿蒙壳工程完整	app/ohos/ 目录	文件齐全
entry 模块能产出	app/ohos/entry/	HAP 能生成
插件全部注册	EntryAbility.ets	4 个插件都 add
权限声明完整	module.json5	INTERNET、MICROPHONE、DLP
路由跳转基本可用	intent_navigation_channel.dart	pageId 能映射

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 --profile

profile 模式下的典型问题：

问题	可能原因	排查方向
语音识别失败	运行态时序问题	检查引擎创建时机
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].material	storeFile、profile、certpath
products 签名配置正确	products[0].signingConfig	应该是 release
SDK 版本匹配	targetSdkVersion	和开发环境一致
兼容版本正确	compatibleSdkVersion	不低于 targetSdkVersion
产物命名正确	output.artifactName	food_voyage

release 模式下的构建命令：

flutter build hap --release

release 模式下的典型问题：

问题	可能原因	排查方向
构建失败	签名材料路径错误	检查 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 模块层 → 入口插件层 → 真机运行层

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

层	debug	profile	release
Flutter 依赖	依赖能构建	依赖能构建	依赖能构建
鸿蒙构建	壳工程完整	壳工程完整	签名配置正确
entry 模块	HAP 能生成	HAP 能生成	HAP 能安装
入口插件	插件注册	插件注册	插件注册
系统能力	能调用	稳定调用	稳定调用
路由跳转	能跳	稳定跳	稳定跳
签名	debug 签名	debug 签名	release 签名

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

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

行为	debug	profile	release
日志输出	完整	部分	最少
断言检查	启用	启用	禁用
调试桥接	启用	启用	禁用
性能优化	无	部分	完整
代码混淆	无	无	可选

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

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

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

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

关键代码位置

文件	构建阶段
app/pubspec.yaml	Flutter 依赖
app/ohos/build-profile.json5	签名、产品、构建模式
app/ohos/entry/build-profile.json5	模块构建目标
app/ohos/entry/src/main/module.json5	Ability、权限、扩展能力
app/ohos/entry/src/main/ets/entryability/EntryAbility.ets	插件注册

常见坑

• 用 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 — 正式签名和产物（签名配置、安装验证、权限验证）

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