Flutter OpenHarmony (鸿蒙) 宿主壳工程说明

本目录为 Flutter 应用的 OpenHarmony (OHOS) 平台承载壳工程。

---

目录结构速览

ohos/
├── AppScope/                  # 应用全局配置与公共资源 (app.json5, app_icon)
├── entry/                     # 主 entry 模块 (EntryAbility, Index.ets, module.json5)
├── hvigor/                    # Hvigor 构建工具配置
├── build-profile.json5        # 工程级构建配置（包含通用占位签名，保持 Git 纯净）
├── hvigorfile.ts              # 工程级构建脚本（集成 flutter 插件与本地动态签名注入插件）
├── signing-config.json.example# 签名配置模板（提交 Git，供新成员参考）
├── signing-config.json        # 本地真实签名配置（已加入 .gitignore，禁止提交）
└── README.md                  # 本说明文档

---

签名配置机制与工作原理解析

1. 为什么采用动态签名注入机制？

• 避免 Git 冲突：DevEco Studio 默认的自动签名功能会把个人开发机的绝对路径（如 /Users/<username>/.ohos/config/xxx.cer）直接写入 build-profile.json5。多人协作或在不同机器间拉取代码时，会造成频繁的 Git 冲突。
• 避免隐私与密钥泄露：个人路径与证书数据隔离在本地文件，不提交到代码仓库。
• 核心实现：本地实际签名存放在 ohos/signing-config.json 中；ohos/hvigorfile.ts 中的 localSigningPlugin 在 Hvigor 构建评估期（afterNodeEvaluate 钩子）读取该文件，并动态覆盖内存中的签名配置。

---

2. 为什么 build-profile.json5 中必须保留占位签名对象（不能是空数组 []）？

在开发与实践过程中发现：

1. Flutter-OHOS CLI 静态前置检查：
   • 华为定制的 flutter-ohos CLI（fvm flutter run）在调用底层 Hvigor 构建前，会在 Dart 层面（flutter_tools/lib/src/ohos/hvigor.dart）用静态文本解析 build-profile.json5。
   • 如果 signingConfigs 数组为空 []，Flutter CLI 会直接拦截并抛出错误：请通过DevEco Studio打开ohos工程后配置调试签名...。
2. Hvigor Schema 枚举校验：
   • signingConfigs 中的 material.signAlg 必须符合鸿蒙 Schema 枚举值（固定为 "SHA256withECDSA"），其余路径字段使用 "placeholder" 字符串占位即可。
3. 两全其美的架构设计：
   • Git 仓库中的 build-profile.json5 保持通用占位符（没有任何个人绝对路径与密钥）。
   • 执行 flutter run 时：Flutter CLI 静态检查通过 → Hvigor 启动 → localSigningPlugin 动态注入本地真实证书 → 成功打出带签名的 HAP 并推送到真机。

---

3. 开发者首次配置步骤（3 步开箱即用）

如果你是首次克隆代码或在新电脑上开发：

1. 复制模板文件：

   cp ohos/signing-config.json.example ohos/signing-config.json

2. 获取你的本机签名材料：

   • 用 DevEco Studio 打开 ohos 工程。
   • 点击菜单栏 File → Project Structure → Project → Signing Configs。
   • 勾选 Automatically generate signature 并点击 Apply 生成签名。
   • 打开 DevEco 写入到 ohos/build-profile.json5 中的 signingConfigs[0].material，将这 7 项材料复制到 ohos/signing-config.json 中保存：
     • certpath
     • keyAlias
     • keyPassword
     • profile
     • signAlg
     • storeFile
     • storePassword
   • 将 ohos/build-profile.json5 还原为带有 "placeholder" 的版本（保持 Git 干净）。

3. 构建与运行：

   • 终端运行：

     # 1. 查看连接的鸿蒙设备 ID
     fvm flutter devices
     # 2. 运行到鸿蒙设备（支持热重载）
     fvm flutter run -d <device_id>

   • 或者在 DevEco Studio 中点击 Run 'entry'，控制台将自动打印：

     [Signing] ✅ 已从 signing-config.json 注入签名配置

---

4. CI/CD 自动化流水线签名注入

在持续集成（CI/CD）打包机上，只需在执行打包前通过环境变量生成 ohos/signing-config.json：

# 示例：CI 步骤中生成签名配置
cat <<EOF > ohos/signing-config.json
{
  "certpath": "$CI_OHOS_CER_PATH",
  "keyAlias": "$CI_OHOS_KEY_ALIAS",
  "keyPassword": "$CI_OHOS_KEY_PWD",
  "profile": "$CI_OHOS_PROFILE_PATH",
  "signAlg": "SHA256withECDSA",
  "storeFile": "$CI_OHOS_STORE_FILE_PATH",
  "storePassword": "$CI_OHOS_STORE_PWD"
}
EOF

# 执行编译打包
hvigorw --mode module -p product=default -p buildMode=release assembleHap

---

常用命令汇总

# 1. 根目录获取 Flutter 依赖
fvm flutter pub get

# 2. 鸿蒙依赖同步
cd ohos && hvigorw --sync -p product=default

# 3. 命令行全量编译 Debug HAP
hvigorw assembleHap --mode module -p product=default -p buildMode=debug

# 4. 命令行运行到鸿蒙真机并启用热重载 (Hot Reload)
fvm flutter run -d <device_id>