这个系列我酝酿了很久。起因很直接团队下一个项目需要覆盖 OpenHarmony 设备但全链路由 ArkTS 重写一遍成本太高于是我们认真评估了 Flutter for OpenHarmony 这条技术路径最后决定用一套 Flutter 代码把 Android、iOS、OpenHarmony 三端一起打通。为了验证这条路在真实业务里走得通我做了个每日热点 App——拉取各平台热榜数据、列表展示、详情页浏览、本地收藏功能不大但覆盖了一个业务 App 的典型链路。这篇是第一篇重心放在项目初始化和鸿蒙插件配置上这也是很多人卡住的第一道坎。官方文档散落在好几个仓库里我把自己实际操作中的版本选型、配置过程和踩过的坑整理出来给打算在 OpenHarmony 上做应用的 Flutter 开发者和技术负责人做个参考。1. 为什么是 Flutter OpenHarmony又为什么选“每日热点”这个小项目1.1 OpenHarmony 应用生态的现状以及 Flutter 的切入点OpenHarmony 这几年的进展确实快设备形态从开发板、手机到 PC 都在覆盖系统底座本身也比较新。但应用侧的现实是ArkTS 生态虽然在快速建设第三方组件库和 SDK 的量级还远不能和安卓、iOS 比。对大多数做业务产品的团队来说所有功能都用 ArkTS 从零重建不现实更合理的选择是一套跨端方案顺手把 OpenHarmony 也覆盖掉Flutter 恰好是这个定位。Flutter 在 OpenHarmony 上能跑起来靠的是 OpenHarmony SIG 维护的一套适配工程。适配方做了三件核心的事情第一把 Flutter 引擎编译到 OpenHarmony 支持的 CPU 架构和系统版本上第二提供 embedder 层让 Flutter 页面能嵌入到 OpenHarmony 的 UIAbility 里这相当于安卓上的 FlutterActivity第三打通 hvigor 和 ohpm 这套 OpenHarmony 原生构建体系让 Flutter 工程最后能打出 HAP 安装包。这套东西的成熟度用一句话概括能用但需要按 OpenHarmony 的工程习惯做配置直接照搬安卓那套思路会踩坑。1.2 每日热点 App 为什么适合做第一个适配项目我见过不少团队一上来就想把大型商业 App 搬到 OpenHarmony结果被插件兼容问题劝退。每日热点这个项目的优点在于它足够小但链路足够全。从技术栈上看它需要网络请求、JSON 解析、状态管理、列表渲染、下拉刷新、WebView 详情、本地收藏这几乎覆盖了一个内容型 App 的全部核心环节。从适配评估的角度看它又是成本可控的就算某个插件在 OpenHarmony 上没有现成实现你也能用很少的代码绕过不至于影响整个项目进度。另外热点类 App 天然适合做演示和验收。热榜数据是公开的拉下来就能看到实时内容不需要自己造数据给业务方展示的时候说服力也强。我把这个项目拆成了一个系列每篇聚焦一个环节方便照着做。1.3 目前适配方案成熟度的客观评估在动手之前建议先把预期管理到位。Flutter for OpenHarmony 目前处于能跑、能业务化、但插件生态需要手补的阶段。纯 Dart 实现的插件比如 dio、provider、riverpod 这些基本开箱即用凡是涉及原生能力的插件比如 WebView、分享、支付、定位、蓝牙必须确认作者有没有提供 ohos 平台实现。就每日热点这个体量的项目来说适配度完全够用。但如果你脑子里想的是安卓那边的插件随便搬那大概率会碰壁。2. 环境准备鸿蒙分支的 Flutter SDK 与工具链版本选型2.1 你下载的 Flutter SDK 不是官方仓库那个我在刚开始准备环境时犯过一个错误用官方 flutter/flutter 仓库的稳定分支执行 flutter create然后发现根本没有 ohos 平台选项。原因很简单OpenHarmony 的适配代码不在官方仓库里而是在 OpenHarmony SIG 维护的 flutter_flutter 仓库下这个仓库是官方 Flutter 的 fork额外带上了 ohos 平台支持。日常使用建议直接通过 git 拉取然后切换到文档推荐的稳定分支。我当时的做法是git clone -b 文档推荐的ohos分支 https://gitee.com/openharmony-sig/flutter_flutter.git export PATH$PWD/flutter_flutter/bin:$PATH这里必须强调一个原则不要追新。SIG 的 fork 版本迭代有自己的节奏它适配的 Dart 版本、引擎版本都是配套锁定的你贸然切到官方最新 Flutter 版本大概率构建期就挂。锁死 SIG 推荐版本后续踩坑也方便搜解决方案。2.2 DevEco Studio、OpenHarmony SDK 与 hvigor 的版本配套Flutter 只是渲染和业务层真正把工程编译成 OpenHarmony 应用还得靠 DevEco Studio 那一套工具链。OpenHarmony 的原生构建用的是 hvigor对标的是安卓里的 Gradle包管理用的是 ohpm对标的是 npm 和 pub。DevEco Studio 里集成了 SDK Manager、模拟器和签名工具这些最好统一从它内部下载。安装完成后还需要把 ohpm 和 hvigor 的路径确认好因为它们会在后续构建中被 Flutter 的 ohos 工具链调用。版本关系不是越新越好而是跟着 Flutter 适配文档走。我在实践中发现DevEco Studio 更新到某一个大版本后旧版本的 hvigor 配置会在构建时报警告所以建议直接采用仓库配套的版本组合不折腾。2.3 多版本 Flutter 共存与环境变量顺序如果你的开发机上原本有官方 Flutter现在又要装一个鸿蒙分支最容易出的问题就是 PATH 顺序。两个 Flutter 的 bin 目录都叫 flutter谁在前谁生效。我之前就把 PATH 写反了执行 flutter --version 看着是鸿蒙分支但 flutter create 出来还是官方模板排查了半天才发现是 PATH 优先级问题。我的习惯是写一个切换脚本而不是直接覆盖全局 PATHexport OHOS_FLUTTER_HOME$HOME/dev/flutter_flutter export PATH$OHOS_FLUTTER_HOME/bin:$PATH每个新终端执行一次确保当前 session 用的是鸿蒙分支。另外配置完成后跑一下 flutter doctor确认没有报错再检查 flutter config --list 看有没有残留的配置干扰。2.4 一份可以直接对照的版本清单下面是我在搭建这套环境时记录的版本组合具体以你拉取的 flutter_flutter 仓库 README 为准组件推荐版本/来源说明Flutter SDKOpenHarmony SIG 的 flutter_flutter 仓库官方仓库无 ohos 平台DevEco Studio适配文档指定版本内置 SDK/模拟器/签名工具OpenHarmony SDKDevEco Studio SDK Manager 拉取工具链版本需与 DevEco 匹配hvigorDevEco 内置或 ohpm 安装对标 Gradle 的构建工具ohpmDevEco 内置或单独安装OpenHarmony 包管理器把这些装好环境就算齐了。下一步就可以创建项目。3. 项目初始化从 flutter create 到理解 ohos 工程结构3.1 创建命令和参数选择环境变量切换到鸿蒙分支后创建项目和官方 Flutter 没什么区别只是加上了 ohos 平台参数flutter create --platformsohos --org com.example daily_hot_news cd daily_hot_news--platformsohos 的意思是只生成 OpenHarmony 平台目录如果你想同时保留 Android 和 iOS可以写 --platformsohos,android,ios。--org 参数决定包名前缀后续做签名和应用市场分发会用到建议一开始就定好公司域名比如 com.yourcompany。这样生成的 HAP 包名就是 com.yourcompany.daily_hot_news中途改包名会牵涉签名文件重新生成比较麻烦。3.2 生成结果里多出来的 ohos 目录初始化完成后项目根部会多出一个 ohos/ 目录。对比一下你就清楚它的定位了平台工程目录构建工具包管理Androidandroid/GradleMaven/GoogleiOSios/XcodeCocoaPodsOpenHarmonyohos/hvigorohpmohos/ 目录里有几个关键文件entry/ 是应用入口模块相当于 Android 的 app modulebuild-profile.json5 记录模块配置和签名信息hvigorfile.ts 是 hvigor 的构建脚本oh-package.json5 声明当前工程的原生依赖。首次打开这个目录时别被 JSON5 后缀吓到它就是带注释和尾逗号的 JSON写起来比标准 JSON 舒服。生成完之后lib/ 目录下默认有个 main.dart 和 counter 示例建议直接把 widget_test.dart 删掉或改成自己的逻辑因为 OpenHarmony 端跑默认测试框架偶尔会有兼容问题没必要在这种地方耗时间。3.3 模块机制HAP、HSP、HAR 分别是什么OpenHarmony 工程里有三种可构建产物理解它们对后续插件配置很重要HAP应用安装包最终装到设备上的东西对应 Android 的 APK。HAR静态共享包编译期打入 HAP 里适合共享代码和资源。HSP动态共享包运行时按需加载适合大型工程拆模块。Flutter 工程默认生成的是 HAP入口模块就是 ohos/entry。你在 DevEco Studio 里打开项目后构建产物可以在 /entry/build/default/outputs/ 下面找到后缀是 .hap。以后如果自己开发插件给团队用会把插件打成 HAR 发布到 ohpm 源消费者通过 oh-package.json5 引入。这里先建立概念就行。3.4 到 Build 之前必须先做的两件事第一次构建前有两件事必须处理否则构建产物没法安装到真机。第一件是签名。用 DevEco Studio 打开 ohos 目录在 File Project Structure Signing Configs 里勾选自动签名Automatically generate signature它会帮你生成调试证书。这一步的前提是登录了 HUAWEI 开发者账号并完成实名认证。如果你们公司不方便用自动签名也可以手动生成 p12、csr、cer 文件再导入但调试阶段用自动签名最省事。第二件是配置 ohpm 仓库。打开 ohos/ 目录下的 oh-package.json5确认项目的依赖声明正确然后执行cd ohos ohpm install第一次 ohpm install 会拉取 OpenHarmony 的基础依赖耗时取决于网络。这里容易犯的错是忘记安装 ohpm 就去跑 flutter build导致构建时提示找不到原生依赖。记住Flutter 的包由 flutter pub get 管OpenHarmony 的包由 ohpm install 管两边都要跑一次。4. 鸿蒙插件配置完整的依赖接入链路4.1 理解插件在 OpenHarmony 上的加载机制Flutter 插件在 Android 上通过 PluginRegistry 注册在 OpenHarmony 上的机制类似但具体位置不同。一个支持 ohos 的 Flutter 插件工程里通常会有 android/、ios/ 和 ohos/ 三个目录ohos/ 目录里是 ArkTS 写的插件桥接代码。当你 flutter pub get 拉到这个插件后构建脚本会识别它的 ohos/ 目录把原生代码编进 HAP同时把 Dart 层的 MethodChannel 和原生层绑定起来。这里有个实用的检查方法去插件仓库看它的目录列表如果有 ohos/ 文件夹说明该插件已经适配如果只有 android 和 ios说明纯 Dart 插件可以正常用原生插件则不行。对每日热点这个项目来说我推荐优先选择有 ohos 支持或纯 Dart 的方案。4.2 pubspec.yaml 与 oh-package.json5 的分层配置很多人被这一层绕晕其实分工很清晰。pubspec.yaml 管理的是 Dart 层面的依赖比如 dio、riverpod执行 flutter pub getoh-package.json5 管理的是 OpenHarmony 原生层面的依赖执行 ohpm install。两者有各自的服务和版本不能混着写。一个典型的 pubspec.yaml 依赖段长这样dependencies: flutter: sdk: flutter dio: ^5.4.0 provider: ^6.1.1 webview_flutter: ^4.7.0 shared_preferences: ^2.2.2其中 dio 和 provider 是纯 Dart在 OpenHarmony 上没有任何问题webview_flutter 和 shared_preferences 必须确认当前版本是否带 ohos 支持。我在项目里用的 webview 是社区 fork 过的 ohos 适配版本pubspec 里直接用 git 依赖指向对应仓库分支。这种用 fork 替代官方包的做法在 OpenHarmony 适配期很常见注意锁定 commit 号别用动态分支。oh-package.json5 则大概长这样{ modelVersion: 5.0.0, description: Daily Hot News OHOS dependencies, dependencies: { }, devDependencies: {} }如果你后续接入了某个需要原生依赖的插件它的 ohos 构建产物 HAR 会通过 ohpm 拉取并出现在这里的 dependencies 里。平时 inspect 这个文件能帮你判断原生依赖是否完整。4.3 联网权限是第一个必踩的坑写网络请求之前先做权限声明。OpenHarmony 的权限配置在 entry/src/main/module.json5 里在 requestPermissions 字段中加入 INTERNET 权限{ module: { name: entry, requestPermissions: [ { name: ohos.permission.INTERNET } ] } }如果不加这个权限运行阶段 dio 请求会直接抛 SocketException而且日志里不会提示你忘了加权限只会看到一个莫名其妙的网络错误。我第一版就是在模拟器里死活请求不到数据还以为是代理或 DNS 的问题最后翻 module.json5 才发现权限漏了。这个坑几乎 100% 会踩建议在工程模板里就默认加上。4.4 每日热点 App 的插件兼容性清单结合项目需求我整理了一份插件选型清单给你做参考需求推荐方案兼容性说明网络请求dio纯 Dart直接可用状态管理provider / riverpod纯 Dart直接可用本地缓存shared_preferences需选择带 ohos 支持的版本或 fork详情页 WebViewwebview_flutter 的 ohos fork官方包暂时未直接支持图片加载cached_network_image依赖图片库建议先用 Image.network 过渡图片加载这块多说一句cached_network_image 底层依赖原生缓存能力在 OpenHarmony 上不一定走通。每日热点这种列表页图片比较多的场景我建议第一版先用 Image.network 把功能跑通图片性能优化放到后续迭代里做。先把链路打通再谈体验优化这是做跨端适配的基本原则。5. 模拟器与真机联调踩坑实录5.1 设备选择DevEco 模拟器、DAYU 开发板还是 x86 的 OpenHarmonyOpenHarmony 的设备形态比安卓丰富联调方式也就更多。DevEco Studio 自带模拟器适合快速验证 UI 和基础交互启动快截图方便但它和真机的行为还是有差异尤其是网络权限和硬件能力。真机方面DAYU200、DAYU210 这类开发板是目前最常见的测试设备ARM 架构和最终商用设备更接近。还有一个容易被忽略的选择OpenHarmony 的 PC 版本。如果你的开发机足够新可以装一个 x86 的 OpenHarmony 系统直接把 HAP 侧载上去跑体验接近桌面应用。对于没有开发板的团队这套方案成本最低。我实际测试下来模拟器跑 Flutter 的渲染流畅度还算可以但热重载的稳定性不如 Android 模拟器真机上则明显更接近最终表现。建议至少准备一台真机别完全依赖模拟器。5.2 三个高频报错与完整的排查链路联调阶段我遇到最多的是下面三个问题每个我都把排查链路走了一遍记录下来免得重犯。报错一安装时提示签名校验失败。典型场景是 hdc install 命令把 HAP 推到设备上结果提示 Install Failed: signature check failed。排查链路先确认 local.properties 或 build-profile.json5 里的签名信息是否配置了再确认签名证书是否是当前设备信任的调试证书。自动签名在 DevEco Studio 里生成的证书只对当前开发者账号绑定的设备列表有效换了一台设备就要重新签署。我的建议是每次连接新设备后都回到 Signing Configs 里重新点一次自动签名然后再构建。报错二网络请求异常Url 无法连接。前面说过90% 的概率是 module.json5 里没加 INTERNET 权限。另外 10% 是模拟器的网络桥接问题。排查时先确认权限声明再用 hdc hilog 查看底层网络错误码如果错误来自模拟器本身换真机再试一次基本能定位。报错三构建时提示找不到某个原生模块或符号。这通常出在插件和基础工具链版本不匹配上。我的排查路径是先 flutter clean删掉 build 目录再在 ohos 目录下执行 ohpm install 重拉原生依赖最后通过 DevEco Studio 重新构建。如果还报错去 flutter_flutter 仓库的 issues 里搜关键词适配阶段的已知问题基本都能搜到解决方案。这种情况说明是插件版本和 Flutter 版本锁定的问题别硬解直接按 issues 里的版本组合调整。5.3 hdc 是 OpenHarmony 的 adb日志排查靠它联调离不开设备调试命令OpenHarmony 的调试工具是 hdc可以理解成 adb 的 OpenHarmony 版本。下面几个命令是日常最高频的hdc list targets # 查看已连接的设备 hdc install xxx.hap # 安装 HAP 包 hdc uninstall com.xxx # 卸载应用 hdc file send xxx.hap /data/local/tmp/ # 推送文件到设备 hdc hilog | grep Flutter # 过滤 Flutter 引擎日志Flutter 层如果用 debugPrint 打的日志通过 hdc hilog 不一定能看到更可靠的方式是用 debugger 在 DevEco Studio 里断点调试原生层Dart 层直接看 Flutter DevTools。我在实践中发现OpenHarmony 上 Flutter DevTools 的 hot reload 功能在 Debug 模式下是正常的但偶发与原生资源相关的更新不及时遇到这种怪现象先单独重启引擎多数能解决。6. 每日热点 App 的工程骨架设计与后续规划6.1 功能范围第一版做到什么程度每日热点 App 第一版我圈定的范围是三个 Tab热点列表、分类浏览、我的收藏。热点列表展示某个聚合源返回的热榜标题和热度值分类浏览按科技、娱乐、体育等维度切换数据收藏页把用户标记过的数据存到本地。点进某条热点后用 WebView 打开详情页。这个范围不大但每一环都在验证 Flutter OpenHarmony 的真实表现。6.2 目录结构与状态管理选型工程目录我按功能分层便于后续每一篇文章往里填内容lib/ ├── main.dart ├── pages/ │ ├── home_page.dart │ ├── category_page.dart │ ├── detail_page.dart │ └── favorites_page.dart ├── models/ │ └── hot_item.dart ├── services/ │ ├── api_client.dart │ └── favorite_store.dart ├── state/ │ └── app_state.dart └── widgets/ └── hot_list_item.dart状态管理我选了 provider原因很朴素它足够成熟、足够简单网上资料多团队成员上手快。Riverpod 在类型安全上更强但对这个项目来说是过度设计。网络层用 dio 封装一个单例 ApiClient统一处理 baseUrl、超时时间和错误码后续文章里再展开。本地收藏第一版用 shared_preferences 存 JSON 数组就够了等数据量上来再考虑上 drift 或 sqflite 的 ohos 适配版。6.3 这个系列接下来的计划到这里项目初始化和鸿蒙插件配置的核心内容就完整了。接下来几个部分我打算按这个顺序推进第二篇做数据层和热点列表渲染重点测试 dio 在 OpenHarmony 上的稳定性第三篇处理 WebView 详情页和页面跳转这是插件适配难度最高的部分第四篇加入收藏功能验证本地存储的持久化表现最后一篇讲打包 HAP、签名配置和应用分发。每篇都会配完整的代码和踩坑记录。最后再分享一个小经验做 OpenHarmony 适配最容易拖垮进度的不是写代码而是文档碎片化。一会儿看 Gitee 仓库一会儿翻 DevEco 文档一会儿又去 issues 里找答案。我的建议是每次装完环境就把版本号、配置截图、踩坑点记在一个文档里形成团队的适配知识库。这比任何官方文档都好用。下一篇见。