鸿蒙Flutter框架 0day适配实战：03 在鸿蒙模拟器/真机上跑 Flutter：从 HAP 构建到截图验证

shao

98人浏览 · 2026-10-28 18:22:05

shao · 2026-10-28 18:22:05 发布

前言

前两篇解决了「SDK 怎么装」：第 1 篇路径 A 用 fvm fork 装分支版本，第 2 篇路径 B 手动 bootstrap tag 版本。装好 SDK 只是开始——让 HAP 构建出来、装进设备、画面真正跑起来，才是消费侧的最后一关，也是坑最集中的一关。

本篇覆盖从环境准备到运行验证的完整链路：

三件套工具链（hdc / ohpm / hvigor）与 PATH 配置；
模拟器 127.0.0.1:5555 的 HAP 安装与 flutter run 直跑；
没有真机证书时，怎么用占位签名出可安装的 HAP；
hdc shell snapshot_display 截图取证，以及模拟器的能力边界。

文末附消费侧 CP1-CP14 踩坑全收录（前两篇散落提到的坑在这里汇总成权威速查表）。全部环境数据来自本机实测（macOS + DevEco Studio 26.0.0 Release + OpenHarmony SDK/API 26，2026-10 记录）。Flutter OH 适配版当前为 3.47.8-ohos-1.0.0；环境搭建见 OpenHarmony-flutter 环境搭建指导。

背景提示：ohos Flutter 是社区分叉（三层架构、三个接缝、七层适配工作见第 1 篇第一章），
SDK 安装与版本核验见第 1、2 篇，本篇只讲「运行」这一段。

一、运行环境全景

1.1 工具链三件套：hdc / ohpm / hvigor

鸿蒙侧运行 Flutter 项目，依赖三组工具，来源不同、职责不同：

工具	来源	职责
`hdc`	OpenHarmony SDK toolchains 目录	设备连接：安装 HAP、执行 shell 命令、拉取文件（鸿蒙版 adb）
`ohpm` / `node` / `hvigor`	DevEco Studio 内置 `Contents/tools`	鸿蒙工程的包管理与构建（hvigor 驱动 HAP 产出）
DevEco Studio 本体	独立安装	SDK 托管（`Contents/sdk`）+ JBR（`Contents/jbr` 内置 JDK）

本机实测的环境变量配置（macOS，路径按自己安装位置改）：

# hdc（鸿蒙设备连接工具，随 OpenHarmony SDK 提供）
H=/Users/zacksleo/Library/OpenHarmony/Sdk/26.0.0/toolchains/hdc

# DevEco Studio 内置工具链：ohpm / node / hvigor
DE=/Applications/DevEco-Studio.app/Contents/tools
export PATH="$H:$DE/ohpm/bin:$DE/node/bin:$DE/hvigor/bin:$PATH"
export DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk
export JAVA_HOME=/Applications/DevEco-Studio.app/Contents/jbr/Contents/Home

三个环境变量里最容易漏的是 DEVECO_SDK_HOME——hvigor 构建 HAP 时按它找 SDK，不配就报 SDK 找不到。JAVA_HOME 指向 DevEco 内置的 JBR 而不是系统 JDK，可以省一次 JDK 版本适配。

1.2 模拟器：127.0.0.1:5555

鸿蒙模拟器启动后，通过 127.0.0.1:5555 暴露 adb/hdc 端口。这个地址会出现在两处：

fvm flutter devices 里它作为一台设备列出；
fvm flutter run -d 127.0.0.1:5555 作为目标设备参数。

模拟器环境的两个特征要提前知道（4.1 节展开）：它是 API 26 环境、不支持部分原生特性（如 HDS 光影），模拟器通过 ≠ 真机通过。

模拟器的获取与启动走 DevEco Studio 自带的 Emulator（与真机不同，不需要任何证书/账号材料），API 版本在创建模拟器时选择。本机记录的组合是 API 26 + oh-3.47.8-release——截图归档时把这两个值一起写进文件名（4.4 节），否则证据无法复现。

1.3 真机连接

真机走 USB 连接，hdc 识别后同样会出现在 fvm flutter devices 的设备列表里（设备号与模拟器不同）。真机验收的三个注意：

首次连接要在设备上确认调试授权；
真机装 HAP 需要匹配的签名 profile（占位签名一般只够模拟器，见第三章）；
真机才是基线——模拟器的 1703/20 与真机的 1723/1723 差距，就是「模拟器数字不能当基线」的最好注脚（第 2 篇 6.1 节、生产侧第 10 篇有完整口径）。

1.4 环境就绪自检：30 秒三层检查

开跑之前花 30 秒把环境三层自检一遍，后面所有异常都能先排除「环境问题」这个最大嫌疑人：

# ① 工具链层：三件套都在 PATH 里
which hdc && which ohpm && which hvigor

# ② SDK 层：flutter 工具链是否报告 ohos 侧就绪
fvm flutter doctor -v

# ③ 设备层：目标设备能否被列出
fvm flutter devices

三层各自的快速判读：

① 有 command not found → 1.1 节的 PATH 没配进当前 shell（~/.zshrc 写了没 source 是最常见原因）；
② doctor 里 ohos 工具链项缺失/红色 → DEVECO_SDK_HOME 或 JAVA_HOME 没生效，echo $DEVECO_SDK_HOME 确认一下；
③ 模拟器没出现 → 模拟器没启动或端口不是 5555；真机没出现 → USB 未授权或 hdc 没识别。

二、在模拟器上跑起来：四步链路

2.1 构建 HAP

在项目根目录执行：

fvm flutter build hap

产物落在 ohos/entry/build/default/outputs/default/ 下，文件名取决于签名配置：

签名配置	产物	可安装性
未配置签名	`entry-default-unsigned.hap`	模拟器可装；真机不行
配置了占位/正式签名	`default-signed.hap`	模拟器可装；真机需匹配 profile

这个「文件名随签名变」的行为是 flutter_tools 的 ohos 构建逻辑决定的，排查构建问题直接读源码（3.2 节给命令）。

2.2 安装 HAP 到模拟器

不走 flutter run，手动装 HAP 验证构建产物（-r 覆盖安装）：

$H install -r <项目>/ohos/entry/build/default/outputs/default/entry-default-unsigned.hap

手动安装的价值：当 flutter run 链路报出难懂的复合错误时，把「构建」和「安装/启动」拆开，能立刻定位问题在哪一半。

2.3 一步到位：flutter run

确认设备在线后，直接跑：

fvm flutter run -d 127.0.0.1:5555 --debug

这条命令串起「构建 → 安装 → 启动 → 日志」全链路，是日常开发的主路径。ohos 工具链的验收标准之一就是热重载可用（对应第 1 篇 1.4 节 L4 层的判据）：r 热重载、R 热重启都应正常响应；返回键与页面生命周期也应在这一档验证。

2.4 截图取证：snapshot_display 三行命令

「跑起来了」不能只凭肉眼，要留下可复核的证据。模拟器/真机截图走 hdc 两步（先截到设备，再拉到本地）：

# 截图保存到设备
hdc shell "snapshot_display -f /data/local/tmp/shot.jpeg"
# 拉取到本地
hdc file recv /data/local/tmp/shot.jpeg ./screenshot.jpeg

下面是 harmony_ui「展示类」组件页跑在鸿蒙模拟器上的注解截图（2026-10-13，模拟器 API 26 + oh-3.47.8-release）：

在这里插入图片描述

上图右侧标注了这张截图能证明的四个事实，正好对应第 1 篇七层工作里的几层验收：

同一份 Dart 代码零改动跑在鸿蒙上（框架层/引擎层三层复用）；
文字、图标、字阶全部正常（字体端口 + 默认字体族在位——第 10 篇要专门讲的「字体静默故障」在这张图里是反例证据）；
鸿蒙长栏来自组件库、不来自系统控件（嵌入层重写 + 组件层自绘）；
列表滚动流畅、无花屏（渲染后端 Impeller Vulkan 交换链正常）。

另一张是 ohos_icons 图标库 gallery 页的真实运行截图（534 个图标、分类筛选、搜索框，DEBUG 构建）：

在这里插入图片描述

图标库页面是「字体/图标端口是否活着」最直接的试纸——534 个图标全量渲染，任何一个缺字都会一眼可见。这类 gallery 页建议每个项目都留一个当验收页。

2.5 热重载与热重启：四项动作验证

ohos 工具链 L4 层的验收标准是「热重载可用；返回键与生命周期正确」。落到操作上是四项动作：

r 热重载：改一处文字/样式后按 r，画面秒级更新且状态不丢（表单输入、滚动位置保留）——画面无反应时先 fvm flutter --version 确认工具链版本对；
R 热重启：应用从 main() 重启，状态全部重置、首帧重建——黑屏时间明显变长要记下来，可能是首帧路径的回归信号；
返回键：每个可 push 的页面按返回键应 pop 当前页，而不是直接退出应用；
生命周期：按 Home 键退后台再回前台，画面应正常重建不丢失。

换新设备或新 SDK 版本时，四项都要重新过一遍；
只测了 r 就说「热重载正常」，是消费侧最常见的验收缩水。

2.6 首屏异常速查

首屏出问题时的三步快查（先排除链路问题，再怀疑代码）：

黑屏：先确认装的是可安装 HAP（3.2 节 shouldCodesign 逻辑），再 fvm flutter devices 确认设备没掉线；
有画面但无文字/图标：这是字体端口信号——消费侧口径是「记录 + 升级/换版本试」，根因诊断见第 10 篇；
能跑但交互错乱（返回键/手势）：先 fvm flutter --version 确认 SDK 与 .fvmrc 绑定的是同一版本，再排查组件层。

三、签名：没有真机证书时怎么出包

3.1 占位签名配置

正式签名需要申请华为开发者证书与 profile。开发/模拟器阶段没有这些材料时，在 ohos/build-profile.json5 的 signingConfigs 里放一套占位材料即可出可安装的 HAP：

{
  "name": "default",
  "type": "OpenHarmony",
  "material": {
    "storeFile": "./signingConfigs/dummy.p12",
    "storePassword": "dummy",
    "keyAlias": "dummy",
    "keyPassword": "dummy",
    "signAlg": "SHA256withECDSA",
    "profile": "./signingConfigs/dummy.p7b",
    "certpath": "./signingConfigs/dummy.cer"
  }
}

两个硬性要求：

type 和 material 字段缺一不可——ohos 工具链按这个结构查找签名材料，缺字段时构建报错或找不到 signed.hap；
占位材料（dummy.p12/p7b/cer）只对模拟器有效，真机安装会因 profile 不匹配被拒。

3.2 shouldCodesign：读源码比猜报错快

配了占位签名后，产物文件名从 entry-default-unsigned.hap 变成 default-signed.hap。这不是玄学，是 flutter_tools 的 ohos 构建逻辑在判断 shouldCodesign：

没有签名配置时，工具链期待的是 default-signed.hap 不存在的路径，安装环节就会扑空；
配了占位签名后，产物路径才是可安装的 HAP。

遇到「构建成功但装不上」「产物文件名对不上」这类问题时，直接读 flutter_tools 源码比对着报错猜快得多（路径以你本机 SDK 版本为准）：

rg -n "signed.hap|unsigned.hap|shouldCodesign|signingConfig" \
  ~/fvm/versions/ohos/oh-3.47.8-release/packages/flutter_tools/lib/src/ohos/

经验：ohos 分叉的 flutter_tools 有独立的 lib/src/ohos/ 目录（13 个源文件，第 1 篇 L6 层），
所有「构建/安装/设备」行为的最终答案都在这个目录里，rg 是首选武器。

四、UI 验证手段与模拟器边界

4.1 模拟器不支持的特性

模拟器是验收的下限，不是上限。本机实测确认的边界：

模拟器不支持原生 HDS 光影等特性——涉及光影效果的组件，在模拟器上看到的不是最终形态，需要自绘等效实现或上真机确认；
模拟器的 API 级别（本机为 API 26）可能与目标真机不同，版本相关的行为差异不能靠模拟器排除。

4.2 「按下去才显示」的效果

按压阴影这类瞬态效果，uitest 的合成触摸无法定格截图（触摸抬起瞬间效果就消失了）。处理策略：

优先用单元测试覆盖逻辑（按压状态机、阴影参数计算）；
视觉验证上真机，用 snapshot_display 连拍或录屏；
自动化验收里把这类效果标记为「人工确认项」，不纳入自动冒烟。

4.3 版本验证的最终口径

运行阶段的所有版本疑问，回到第 2 篇的三层核验：fvm flutter --version 横幅 + flutter.version.json 元数据。运行日志里的版本号、HAP 里的 manifest、SDK 目录名三处对不上时，一律以 flutter.version.json 为准。

4.4 截图证据的归档规范

截图不是「跑起来了」的自证，而是可复核的证据。归档四件事：

命名：<日期>_<SDK版本>_<设备>_<页面>.jpeg，例如 20261013_3.47.8-ohos-1.0.0_emulator-api26_gallery.jpeg——2.4 节注解图右下角标「模拟器 API 26 · oh-3.47.8-release · 截图 2026-10-13」就是这个口径；
存放：项目内 docs/screenshots/ 或专门证据目录，随代码提交进仓库；
说明：每张截图配一行「它证明了什么」（2.4 节右侧标注的四个事实就是模板）；
报障成套：反馈问题时截图必须与 flutter.version.json 摘录成对出现，对方不用追问版本就能复现。

五、验收判据：模拟器、真机与三档

5.1 三档判据

消费侧的验收分三档，逐档递进（生产侧的完整验证门 M0-M5 见第 5 篇 §6.4，设备侧证据见第 10 篇）：

档	在哪跑	能证明什么	典型命令
冒烟档	模拟器 debug	构建链路通、画面出来、热重载可用	`fvm flutter run -d 127.0.0.1:5555 --debug`
功能档	真机 debug	签名匹配、生命周期/返回键正确、光影等真机特性	`fvm flutter run -d <真机设备号>`
交付档	真机三档（debug/profile/release）	交付形态完整，AOT/优化路径无回归	`fvm flutter build hap --release` + 安装 + `snapshot_display`

5.2 模拟器的数字不是基线

生产侧验证时拿到过一组对照：同一套引擎单测，模拟器 1703 通过 / 20 失败（纯环境性：无 Vulkan 设备、QoS 差异），真机 1723/1723 全绿。把模拟器的数字当基线，会把 20 个环境性失败误判成回归。

消费侧的对应口径：模拟器冒烟通过只说明「链路没断」；
谈「能不能交付」之前，真机 debug 档至少完整走一遍。

5.3 三档验收清单

把 5.1 的三档拆成可打勾的清单（每项都对应前文某个验证手段）：

档	清单项	通过标准	对应手段
冒烟档	`flutter doctor -v` 无缺失项	ohos 工具链项全绿	1.4 节三层自检
冒烟档	HAP 构建 + 安装成功	`install -r` 返回成功	2.1/2.2 节
冒烟档	首帧出现 + 热重载可用	`r` 秒级生效、状态不丢	2.3/2.5 节
功能档	返回键 / 生命周期正确	每页可 pop、回前台不丢画面	2.5 节
功能档	文字 / 图标 / 字阶正常	gallery 页全量渲染无缺字	2.4 节试纸
功能档	滚动无花屏 / 掉帧	目测 + 截图留证	2.4 节
交付档	`build hap --release` 成功	AOT / 优化路径无回归	5.1 节
交付档	真机安装 + 启动 + 截图归档	profile 匹配、证据成套	2.4/4.4 节

六、常见问题 FAQ：消费侧 CP1-CP14

前两篇各自带了踩坑速查/FAQ 章节，这一节把消费侧（用别人发好的 SDK）的全部 14 个坑汇成权威速查表，按实际发生顺序编号，每条「现象 → 原因 → 处理」：

#	现象	原因	处理
CP1	`curl` 抓 release 页面挂起	release 页是 JS 渲染 SPA，HTML 里没有下载链	用 `git ls-remote --tags` 探测 + `git clone --branch` 下载（第 2 篇 2.1 节）
CP2	`timeout` 命令 not found	macOS 无 GNU coreutils 的 `timeout`（brew 装了才是 `gtimeout`）	后台进程 + `sleep` + `kill` 手工限时（第 2 篇 2.1 节）
CP3	旧文章/脚本里的仓库域名与实际不符	仓库已统一迁移到 AtomGit	仓库地址一律写 `https://atomgit.com/<org>/<repo>.git`
CP4	首次安装下载慢/卡住	未切国内镜像，走海外 OBS 慢速通道	镜像环境变量 + 本地代理两条都上（1.1 节同思路）
CP5	`fvm install ohos/<tag名>` 失败	fvm fork 机制只认分支名，tag 不在分支列表里	tag 版本手动 clone 到 `~/fvm/versions/ohos/<名字>`（第 2 篇）
CP6	首次初始化卡在 `Resolving dependencies`	flutter_tools pubspec 有 SSH 依赖 URL，本机无 SSH 凭据	两处换成 HTTPS 后重跑（第 2 篇 2.4 节）
CP7	首次初始化耗时 1 分钟+，中断后更慢	要下载定制 Dart SDK + 编译 flutter tool；`bin/cache` 半成品触发重下	保证网络后耐心等，别 Ctrl-C（第 2 篇 2.3 节）
CP8	pub 建议 `Try using the Flutter SDK version: 3.47.6`	建议值是上游官方版本，本机装不了	换满足约束的 ohos 分叉版本（第 1 篇第八章）
CP9	分支名与实际版本不一致（如装 `oh-3.44.9-dev` 显示 `3.44.9+ohos-0.0.1-canary1`）	分支 HEAD 持续合入补丁，版本号随补丁递进	对外写框架版本号；一切以 `flutter --version` 与 `flutter.version.json` 为准
CP10	在 `~/.fvm/` 下找不到 fork 配置	fvm 4.x 缓存目录是 `~/fvm/versions`，不是 `~/.fvm`	以 `fvm list` 首行 `Cache directory` 为准
CP11	队友 clone 项目后 `flutter` 命令失效	`.fvm/` 软链被提交进仓库，指向你的绝对路径	`.fvm/` 加入 `.gitignore`，队友自行 `fvm use`（第 1 篇 4.3 节）
CP12	用上游 `engine.version` 对比 ohos 引擎「对不上」	ohos 定制引擎与上游版本号故意不同	看 `engine.ohos.version`，不与上游对比（第 1 篇 7.2 节）
CP13	AtomGit 直连慢/卡	公司网络或代理未配置	设 `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY`（第 2 篇 2.2 节）
CP14	切了 SDK 仍 `version solving failed`	`.fvmrc` 没切对，或旧 `.dart_tool` 缓存残留	`fvm flutter --version` 确认后清缓存重跑（第 2 篇 5.1 节）

6.1 四个高频坑展开

CP4（下载慢）的标准解法是两条一起上——只切镜像解决存储类下载，git 类操作还要走代理：

# fvm / pub：换国内镜像
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
export PUB_HOSTED_URL=https://pub.flutter-io.cn

# git 操作：走本地代理（按自己环境改端口）
export HTTP_PROXY=http://127.0.0.1:1087
export HTTPS_PROXY=http://127.0.0.1:1087
export ALL_PROXY=socks5://127.0.0.1:1080

CP5（fvm 装不了 tag）的本质：fvm 管理的是「仓库 + 分支」，不是「仓库 + tag」。它不是 bug 而是设计边界——所以解法不是给 fvm 提 issue，而是手动 bootstrap 把 tag 版本「放进去」（第 2 篇整篇）。

CP8（上游版本号误导）的判别口诀：pub 报错里出现 Try using the Flutter SDK version: X.Y.Z 且 X.Y.Z 不带 -ohos 后缀，就是上游版本——照着装必失败，正确动作是查分叉 tag 线里功能对应的版本。

CP9（分支名 ≠ 版本号）的对外口径：对外声明版本时写框架版本号（如 3.47.8-ohos-1.0.0 或 3.44.9+ohos-0.0.1-canary1），不写分支名；分支名只是「安装时的把手」。

生产侧（fork 维护者）的 P1-P29 踩坑体系与消费侧 CP 系列完全无重叠——
那是「自己编引擎/发 SDK」时的坑，完整明细分散在 07、08、10 三篇，索引表见第 5 篇。

6.2 版本与依赖快问快答

现在应该装哪个 Flutter OH 版本？ 当前发布线是 3.47.8-ohos-1.0.0；旧项目对照可选 3.44.9 线。装完用 fvm flutter --version 核对实际版本。

DevEco Studio 与 API 版本？ DevEco Studio 26.0.0 Release，OpenHarmony SDK/API 26；DEVECO_SDK_HOME 指向 .../Contents/sdk。

本篇需要 pubspec / git 依赖吗？ 不需要。本篇只涉及 Flutter OH SDK 的运行链路；harmony_ui 等组件库的引入方式见对应组件文章。

6.3 坑索引：每个坑在哪篇展开

坑	首现篇目	详细展开位置
CP1 release 页 SPA	02	第 2 篇 2.1 节
CP2 macOS 无 timeout	02	第 2 篇 2.1 节
CP3 仓库地址统一 AtomGit	01	第 1 篇 2.2 节
CP4 下载慢/卡	01	本篇 6.1 节（标准解法）
CP5 fvm 装不了 tag	01	第 2 篇整篇
CP6 SSH 依赖 URL	02	第 2 篇 2.4 节
CP7 首次初始化中断	02	第 2 篇 2.3 节
CP8 上游版本号误导	01	第 1 篇第八章 + 本篇 6.1 节口诀
CP9 分支名 ≠ 版本号	01	第 1 篇 3.1 节 + 本篇 6.1 节口径
CP10 fvm 缓存目录	02	第 2 篇 2.2 节
CP11 `.fvm/` 软链入库	01	第 1 篇 4.3 节
CP12 引擎版本对比口径	01	第 1 篇 7.2 节
CP13 AtomGit 直连慢	02	第 2 篇 2.2 节
CP14 切 SDK 仍解析失败	02	第 2 篇 5.1 节

七、从零到首屏：完整命令序列

把第 1-3 篇的命令串成一条主线（全新机器视角，当前 tag 版本路线）：

# 0. 镜像与代理（6.1 节 P4 标准解法）
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
export PUB_HOSTED_URL=https://pub.flutter-io.cn

# 1. 按 tag 浅克隆当前 SDK（第 2 篇路径 B）
git clone --depth 1 --branch 3.47.8-ohos-1.0.0 \
  https://atomgit.com/oh-flutter/flutter_flutter.git \
  ~/fvm/versions/ohos/oh-3.47.8-release

# 2. 项目内切换
cd <项目目录> && fvm use ohos/oh-3.47.8-release

# 3. 三层自检（第 1 篇 5.4 节）
fvm list && fvm flutter --version
cat ~/fvm/versions/ohos/oh-3.47.8-release/bin/cache/flutter.version.json

# 4. 鸿蒙工具链环境（本篇 1.1 节）
export PATH="$H:$DE/ohpm/bin:$DE/node/bin:$DE/hvigor/bin:$PATH"
export DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk
export JAVA_HOME=/Applications/DevEco-Studio.app/Contents/jbr/Contents/Home

# 5. 跑起来（模拟器）
fvm flutter run -d 127.0.0.1:5555 --debug

# 6. 截图取证（本篇 2.4 节）
hdc shell "snapshot_display -f /data/local/tmp/shot.jpeg"
hdc file recv /data/local/tmp/shot.jpeg ./screenshot.jpeg

六步走完，「装 SDK → 跑起来 → 留下证据」的消费侧闭环就完成了。

八、系列导航

本文是「鸿蒙Flutter框架 0day适配实战」系列的第 3 篇，消费侧三篇到此完结。全系列 10 篇：

#	篇目	侧	一句话主题
01	背景、分叉谱系、版本命名与 fvm fork 安装	消费	三层架构、三个接缝、七层工作量、路径 A、版本墙
02	手动 bootstrap tag 版本与三层核验	消费	tag 探测、浅克隆、首次初始化、SSH 修复、异常分诊
03	鸿蒙模拟器/真机跑 Flutter + 消费侧踩坑集（本篇）	消费	工具链三件套、HAP 构建/安装/运行、占位签名、截图取证、CP1-CP14
04	flutter build hap 自动签名	消费	P12/CSR、AGC 证书与 Profile、纯 Dart AES-GCM、C0-C10 复用
05	上游同步总览、BC 全景与端到端 SOP	生产	批次解剖、五阶段验证门、12 项适配表、端到端 SOP 与 P1-P29 索引
06	Phase 1+2：基线建立与 Framework 适配	生产	代理 HTTP/1.1 修障、421 文件重打、Dart SDK 源码构建
07	Phase 3 Engine：三方重放与冲突裁决	生产	826 文件、15 真冲突两分法、契约对齐 16 项
08	引擎构建链攻防	生产	依赖树、工具链版本、链接与测试面 27 坑
09	构建发布与产物分发	生产	版本锁、11 个工件（Dart SDK 双宿主）、11 条覆盖键、换新 tag 铁律
10	验证与真机验收	生产	三档引擎、设备侧单测、字体图标静默故障

配套仓库与文档：

oh-flutter 分叉仓库（当前 tag 3.47.8-ohos-1.0.0）：atomgit.com/oh-flutter/flutter_flutter
Flutter OH 环境搭建指导：https://atomgit.com/oh-flutter/flutter_samples/blob/master/ohos/docs/03_environment/OpenHarmony-flutter%E7%8E%AF%E5%A2%83%E6%90%AD%E5%BB%BA%E6%8C%87%E5%AF%BC.md
自研组件库 harmony_ui（本篇截图主角）：atomgit.com/oh-flutter/harmony_ui

总结

消费侧三篇到这里闭环：第 1 篇背景 + 路径 A，第 2 篇路径 B + 版本核验，本篇把 HAP 真正跑到了模拟器/真机上——工具链三件套配好 PATH，flutter build hap 出包，install -r 或 flutter run 装进 127.0.0.1:5555，没有证书就用占位签名，验收靠 snapshot_display 截图取证，P1-P10 踩坑全收录兜底。记住两条口径：模拟器通过只是链路没断，真机才是基线；构建行为对不上时，rg flutter_tools 的 lib/src/ohos/ 目录永远比猜报错快。

下一篇（第 4 篇）补上消费侧最后一块：flutter build hap 自动签名——为 flutter_tools 增加 11 文件、79 个单测的签名模块，让一条命令直接产出可装真机的签名 HAP，不再手动过 DevEco Studio。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

oh-flutter 分叉仓库（当前 tag 3.47.8-ohos-1.0.0）：atomgit.com/oh-flutter/flutter_flutter
Flutter OH 环境搭建指导：OpenHarmony-flutter 环境搭建指导
DevEco Studio 26.0.0 Release 下载：developer.huawei.com
OpenHarmony 官方文档（API 26）：gitcode.com/openharmony/docs
fvm 多版本管理器：github.com/leoafarias/fvm
Flutter 官方架构文档：docs.flutter.dev
pub 国内镜像：pub.flutter-io.cn
Flutter 国内镜像配置说明：docs.flutter.cn（镜像与代理）
开源鸿蒙跨平台社区：openharmonycrossplatform.csdn.net

环境与版本

本文的示例与截图基于以下环境组合（2026-10 实测）：

组件	版本	说明
上游 Flutter SDK	3.47.8	github.com/flutter/flutter
Flutter SDK（OH 适配版）	3.47.8-ohos-1.0.0	oh-flutter/flutter_flutter，`oh-3.47-dev` 分支
DevEco Studio	26.0.0 Release	提供 hvigor / ohpm / hdc / JBR 等工具链
OpenHarmony SDK / API	API 26（26.0.0）	模拟器与 SDK 均为 API 26
运行设备	OpenHarmony 模拟器	API 26，1280×2832