
本文来源:https://www.hqwc.cn/a/1647615.html
若有版权问题,请来信告知:13951431913#139.com 或在右方提交评论。
Flutter跨端开发实战:从零搭建OpenHarmony计数器应用
举个最简单的场景:一个计数器应用,页面上一个数字,几个按钮,加一、减一、清零。单看功能,它确实不难,但如果要在 Android、iOS、OpenHarmony 三个平台各写一遍,工程量就从“一个页面”变成了“三套工程”。我这段时间做的事,就是拿 Flutter 把这套简易数字累加器做成真正的三端应用,其中 OpenHarmony 端从环境配置到真机部署,几乎每一步都踩了文档没写清楚的坑。这篇文章就把完整的开发指南和避坑过程拆开讲,目标读者是正在评估 Flutter 跨端到 OpenHarmony 的团队,以及想把手头 Flutter 应用移植到鸿蒙设备上的开发者。
这个项目本身不复杂,但它的价值不在功能,而在验证一套链路:同一份 Dart 代码能不能在 OpenHarmony 上正常渲染、正常响应事件、正常打包上真机。同时它也是评估 Flutter 三端方案最便宜的试金石——如果连计数器都跑不通,那复杂的业务应用更不用谈。下面我按实际操作的顺序,从环境准备、核心实现、构建调试到扩展方向,把完整过程写出来。
1. 为什么要跑到 OpenHarmony 上,以及它跟 Android 侧的本质差异
先说一个很多人上来就搞错的点:OpenHarmony 不是 Android,它不能直接跑 APK,也不能用官方 Flutter SDK 构建出可安装的鸿蒙应用。官方 Flutter 的国内镜像、SDK 下载,默认只生成 android、ios、web、windows、macos、linux 这些平台目录,里面根本没有 ohos 这个选项。
OpenHarmony 端的 Flutter 适配,是 OpenHarmony SIG 团队在维护的,代码放在 flutter_flutter 仓库的 ohos 分支里。它做的事情,是把 Flutter 引擎层通过 OpenHarmony 的 Native API 接进去,让 Dart 侧的 UI 渲染、事件分发、布局计算全部在 Flutter 自绘引擎里完成,最后输出一个原生的 OpenHarmony 应用壳。
Dart 侧代码(也就是你的业务逻辑和 UI)完全跨端复用,不用改。
Android/iOS/OpenHarmony 各自只保留一个原生壳工程,负责启动 Flutter 引擎。
平台能力调用(图库、支付、定位、数据库)必须通过通道桥接,不能直接写平台相关代码。
理解了这一点,后面遇到什么“为什么我 flutter create 出来没有 ohos 目录”这类问题,就不会慌。
很多团队评估 Flutter 跨端时,第一个担心的是“UI 能复用,业务逻辑是不是也得各写一份”。实际上,我用这个累加器项目验证下来,复用的边界非常清晰:
界面布局:全部复用,用的是同一套 Widget。
交互逻辑:全部复用,点击、加减、清零都是 Dart 代码。
状态管理:全部复用,setState 就是平台无关的。
原生能力:不复用,必须用 MethodChannel/EventChannel 桥接。
工程配置:不复用,Android 的 gradle、iOS 的 Xcode、OpenHarmony 的 DevEco 工程各不相同。
所以做三端应用,核心原则就一句话:Dart 侧能做的,全部留在 Dart 侧;必须碰系统的,才开放通道。这个累加器项目里,我甚至没有写任何 Platform 判断——同一份代码,在三个端跑出来的效果完全一致。
2. 环境准备:版本匹配是最大的前提
OpenHarmony 生态迭代太快,版本不匹配导致的编译报错,占了整个环境搭建阶段八成以上的时间。你在网上搜到的教程,可能一个月前还成立,现在就跑不通了。我这次使用的组合大致是:
Flutter SDK:flutter_flutter 仓库的 ohos 分支,选一个和 OpenHarmony SDK 匹配的 tag
系统环境:Windows 10/11,开发过程中用到了命令行和 DevEco Studio 的终端
为什么版本匹配这么重要?因为 Flutter 引擎需要调用 OpenHarmony SDK 的底层接口,如果 SDK 换了接口但引擎没跟上,编译期会直接报找不到符号;反过来,SDK 太老而引擎太新,又会出现链接错误。这个没有通用解法,最靠谱的方式是去 flutter_flutter 仓库的 README,看它明确说明支持哪个 OpenHarmony 版本。
第一步,安装 DevEco Studio。装的时候记得把 OpenHarmony SDK 组件一起拉下来,路径要记好,后面配环境变量用。如果只装 IDE,不装 SDK,Flutter 那边连设备都识别不到。
第二步,拉取 Flutter SDK 的 ohos 分支。这里我踩了个坑:刚开始直接用了官网下载的 Flutter SDK,忙活半天才发现没有 ohos 支持。正确做法是单独 clone 一份:
具体分支名以仓库发布为准,不同时期分支名可能不同。拉完之后,把这份 flutter 的 bin 目录加到 PATH 里。
第三步,配置环境变量。除了 PATH,还需要设置 OpenHarmony SDK 的路径。我当时是这么配的:
这里有一个非常基础但极其容易踩的坑:环境变量配置完成后,必须新开一个终端窗口才生效。我当时在旧终端里反复执行 flutter doctor,一直提示找不到 SDK,以为是变量写错了,折腾了小半天,结果只是终端没重开。
第四步,用 flutter doctor 检查环境。如果 ohos 工具链正常,它会列出 OpenHarmony 相关的状态。如果提示找不到 hdc 或者 SDK,优先检查环境变量有没有真正传进当前终端:
创建完成后,工程里会多出一个 ohos 目录,这就是 OpenHarmony 的原生壳。
我在做 Flutter 开发时习惯用命令行创建项目,因为 IDE 的模板工程往往会夹带一些版本不明确的依赖,命令行创建出来的工程目录结构更干净,后面手动改配置时不容易被多余的壳干扰。而且 flutter create 是支持 --platforms 参数的,需要哪个平台就生成哪个平台,非常灵活。
如果你还是觉得环境准备这一步太麻烦,我的建议是:先跑通官方示例,不要一上来就迁移自己的业务项目。拿 hello_world 级别的应用在 OpenHarmony 上跑通,确认环境没问题,再逐层叠加复杂度。
3. 累加器核心实现:同一套代码跑三端
简易数字累加器的功能很简单:页面中央显示一个数字,提供“加一”“减一”“清零”三个操作。我把代码组织成这样一个结构:
项目虽小,但建议把页面和逻辑稍微分一下。后面如果要做本地数据库、网络同步,逻辑层独立出来会好扩展得多。
状态管理我用的是最朴素的 setState,没有引入 Provider 或 Riverpod。原因很简单:这个项目的核心是验证三端适配,不是验证状态管理框架,变量越少越容易定位问题。
这套代码不管在 Android 还是 OpenHarmony 上,渲染效果基本一致。唯一需要注意的是:OpenHarmony 真机上如果遇到中文字体显示异常,通常是系统字体库缺失,需要引擎层配置,这一点在部分早期版本上出现过。我在最新的 5.x 版本上测试,中文显示正常,没有额外处理。
我自己执行验证的顺序是:先 Android 模拟器,再 OpenHarmony 真机,最后跑 iOS 模拟器。为什么先跑 Android?因为 Flutter 的调试工具链和 Gradle 生态最成熟,报错信息也更完整,可以先把业务代码层面的问题清干净。然后再跑 OpenHarmony,重点关注平台壳、引擎加载、权限配置这些 Android 上没有的问题。最后跑 iOS,确认没有平台差异回退。
在验证过程中,我还刻意做了一件事:整个 lib 目录里没有出现 if (Platform.isAndroid) 这种判断代码。一旦出现,说明复用的“纯度”不够,需要回头检查设计。
4. 构建到 OpenHarmony 设备时的真实问题与排查链路
在 OpenHarmony 端跑构建时,我遇到一个比较典型的报错:
这个报错看起来很吓人,其实就是 OpenHarmony 工程模板里的 Gradle 配置方式和新版 Flutter Android 插件的注册方式对不上的问题。新版 Flutter Android 工程推荐在 settings.gradle 的 pluginManagement 里统一声明插件,然后在根 build.gradle 里用 plugins 块声明应用;而 OpenHarmony 旧模板里可能是直接 apply plugin: 'dev.flutter.flutter-gradle-plugin' 这种命令式写法。
第一步,看 Android 侧的 build.gradle,确认 Flutter 新版模板长什么样。
第二步,对比 ohos 工程里 flutter 插件有没有走同样的插件管理逻辑。
第三步,在 ohos 工程里把命令式 apply 改成 plugins 块声明方式,或者反之,根据模板的 Gradle 版本来定。
如果一个模板工程刚生成就报这个错,还有一种可能是两个工程的文件混用了。比如在 Android 目录里改过 gradle 文件,然后把配置拷贝到了 ohos 目录。OpenHarmony 的原生壳是独立工程,Gradle 配置不能直接搬,必须用模板自带的那份改。
这个问题的本质是:OpenHarmony 的 Flutter 适配版本与上游 Flutter Android 插件更新节奏不完全同步。解决思路不是去记某一种写法,而是看当前 Flutter 版本期望哪种写法,再去对齐模板。
OpenHarmony 真机安装应用比 Android 麻烦一些。Android 调试时签名可以直接用 debug keystore,OpenHarmony 则需要配置调试证书,包含 .p12、.cer、.p7b 三个文件。我第一次跑 flutter run -d 时,设备列表里根本看不到 OpenHarmony 设备,就是因为 hdc 没有正确识别,或者设备没有进入开发者模式。
在 OpenHarmony 设备上开启开发者模式和 USB 调试。
用 hdc 连接设备,确认能被识别:
在 DevEco Studio 里用自动签名生成调试证书。如果你不把证书配置到 ohos 工程的 build-profile.json5 里,构建出来的应用在真机上会被拒绝安装。
这里我想提醒一点:OpenHarmony 的 hdc 命令路径和 adb 不一样,可能不在 Flutter 的依赖目录里,而是在 DevEco Studio 的 SDK 目录下。如果 hdc 命令找不到,记得配环境变量或者用全路径执行。
OpenHarmony 端的日志系统是 hilog,不是 logcat。调试 Flutter 时,很多 dPrint 输出不会直接出现在终端,需要用 hilog 过滤:
这个和 Android 上 adb logcat | grep flutter 的操作思路一致,只是命令更单调。
热重载在 OpenHarmony 端能用,但和 Android 比偶发失效。改动纯 Dart 代码时, r 键很好使;更改原生壳配置或依赖时,往往需要全量重启。我建议在做 OpenHarmony 适配时,不要把热重载当成默认依赖,遇到不生效就老老实实全量构建,反而更快。
还有一个调试细节:OpenHarmony 真机上应用启动后,如果页面白屏,优先看膨胀后的原生应用有没有正确加载引擎。这个问题在模拟器上不太容易出现,真机上因为设备资源限制,偶尔会有引擎初始化慢导致的启动延迟,需要区分是卡死还是慢启动。
把三端都跑通之后,我整理了一份日常开发效率的对比,供大家参考:
OpenHarmony 的 Flutter 生态还处在快速变化期,很多问题你搜索时找不到现成答案,需要用 Android 侧的思路类推。这时候,理解底层机制比背结论重要得多。比如报错发生在引擎层,那就去对照 Android 侧 Flutter 引擎的加载方式,往往能找到突破口。
累加器本身不需要调用系统能力,但如果你后续要在 OpenHarmony 上做更复杂的应用,一定会碰到通道对接。比如“调用鸿蒙的图库”和“拉起 IAP 支付”,这属于典型的原生能力,Dart 侧只管发指令,真正干活的是 ArkTS 侧的逻辑。
这个累加器跑通后,我顺手验证了几个常见扩展方向,先说结论:基础能力都能用,差异在细节。
内嵌数据库:sqflite 系在 OpenHarmony 上可以跑,但注意原生文件路径的获取方式与 Android 不一致,路径要按 OpenHarmony 的沙箱规则去取。如果只是本地少量数据,也可以直接考虑轻量级存储。
网络请求:dio 在 OpenHarmony 上可以正常工作,抓包时注意不要只盯着 Android 的代理,OpenHarmony 的 https 证书信任逻辑和 Android 可能不同,开发阶段建议把证书配置搞清楚,不然线上环境容易踩 HTTPS 握手失败的坑。
动画素材:lottie 加载网络 zip 包的模式在 OpenHarmony 上也能跑,但要注意压缩包的解压路径和应用沙箱权限,和 Android 的 cache 目录不是一回事。
这些都说明一个事:Flutter 三端应用的核心优势在 Dart 侧,但每个端的“原生边缘”都存在差异,不能用同一个假设套所有平台。
最后分享一个我个人的实操体会:做 OpenHarmony 的 Flutter 开发,耐心比技术本身更重要。环境搭建阶段遇到的问题,大部分是版本错位,这需要时间去查、去比对、去试错;一旦把环境跑通,后面写业务代码的体验和 Android 上差别不大。如果你正准备评估 Flutter 在鸿蒙生态里的可行性,建议从这种最简单的累加器起步,把它跑上真机,亲自感受一遍从环境配置到构建部署的完整流程,再决定要不要投入更大规模的项目。

本文来源:https://www.hqwc.cn/a/1647615.html
若有版权问题,请来信告知:13951431913#139.com 或在右方提交评论。
Take the simplest scenario: a counter app with a number on screen and a few buttons to increment, decrement, and reset. On its own it is not hard, but writing it once each for Android, iOS, and OpenHarmony turns 'one page' into 'three projects.' What I have been doing recently is using Flutter to turn this simple number accumulator into a genuine three-platform app, and on the OpenHarmony side, from environment setup to on-device deployment, almost every step hit a pit the docs did not explain. This article breaks down the complete development guide and the troubleshooting process, aimed at teams evaluating Flutter across platforms to OpenHarmony and developers wanting to port existing Flutter apps to HarmonyOS devices.
The project itself is not complex, but its value lies not in function: it validates a chain, whether the same Dart code can render, respond to events, and package onto a real device on OpenHarmony. It is also the cheapest litmus test for the three-platform Flutter approach, because if even a counter cannot run, complex business apps are out of the question. I will write the complete process in actual operation order, from environment preparation and core implementation to build, debugging, and extension directions.
1. Why run on OpenHarmony and how it fundamentally differs from Android
First, a point many people get wrong at the outset: OpenHarmony is not Android. It cannot run APKs directly, and the official Flutter SDK cannot build an installable HarmonyOS app. The official Flutter domestic mirror and SDK downloads by default generate only platform directories for android, ios, web, windows, macos, and linux; there is no ohos option.
Flutter adaptation for OpenHarmony is maintained by the OpenHarmony SIG team, with code in the ohos branch of the flutter_flutter repository. What it does is connect the Flutter engine layer through OpenHarmony's Native APIs, so Dart-side UI rendering, event dispatch, and layout calculation all complete inside Flutter's self-drawn engine, finally outputting a native OpenHarmony app shell.
Dart-side code, your business logic and UI, is fully cross-platform reusable without changes; Android, iOS, and OpenHarmony each keep only one native shell project to start the Flutter engine; platform capabilities such as gallery, payment, location, and database must be bridged through channels rather than written as platform-specific code. Understanding this will keep you calm when you hit questions like 'why did my flutter create produce no ohos directory.'
When teams first evaluate Flutter cross-platform, a common worry is whether business logic must be written separately even if UI can be reused. With this accumulator project I verified the reuse boundary is very clear: interface layout is entirely reused with the same widgets; interaction logic is entirely reused, with clicks, increment, decrement, and reset all in Dart; state management is entirely reused, since setState is platform-independent; native capabilities are not reused and must be bridged with MethodChannel/EventChannel; project configuration is not reused, since Android's gradle, iOS's Xcode, and OpenHarmony's DevEco projects all differ. So the core principle for three-platform apps is simple: whatever Dart can do stays in Dart, and only what must touch the system opens a channel. In this accumulator I did not even write any Platform checks; the same code produced identical results on all three platforms.
2. Environment preparation: version matching is the biggest prerequisite
The OpenHarmony ecosystem iterates so fast that version-mismatch compile errors take up more than 80% of the entire environment setup phase. A tutorial you find online may have worked a month ago and no longer work now. The combination I used was roughly: Flutter SDK from the flutter_flutter repository's ohos branch, choosing a tag matching the OpenHarmony SDK; system environment Windows 10/11, using the command line and DevEco Studio's terminal during development.
Why is version matching so important? Because the Flutter engine calls low-level OpenHarmony SDK interfaces: if the SDK changes an interface but the engine has not caught up, compilation fails with missing symbols; conversely, an old SDK with a new engine produces link errors. There is no universal fix; the most reliable way is to read the flutter_flutter repository README for the explicitly supported OpenHarmony version.
Step one, install DevEco Studio, remembering to pull the OpenHarmony SDK components together and noting the path for later environment variables; installing only the IDE without the SDK means Flutter cannot even detect the device. Step two, pull the Flutter SDK's ohos branch. I hit a pit here: I first used the Flutter SDK downloaded from the official site and wasted half a day before realizing it had no ohos support. The correct approach is to clone a separate copy; the exact branch name depends on the repository release, as names may differ over time, and afterward add that flutter's bin directory to PATH. Step three, configure environment variables: besides PATH you need to set the OpenHarmony SDK path. A very basic but extremely easy pitfall: after configuring environment variables you must open a new terminal window for them to take effect. I kept running flutter doctor in the old terminal, kept getting 'SDK not found,' and wasted half a day only to realize the terminal simply had not been reopened. Step four, check the environment with flutter doctor; if the ohos toolchain is normal it will list OpenHarmony-related status, and if it reports missing hdc or SDK, first check whether the variables actually reached the current terminal.
Once created, the project gains an ohos directory, the native shell for OpenHarmony. I prefer creating projects from the command line because IDE template projects often carry dependencies with unclear versions, while command-line projects have cleaner structure and are less likely to be disturbed by extra shells when you change configuration manually. flutter create also supports the --platforms parameter, so you generate only the platforms you need. If environment preparation still feels troublesome, my advice is to run the official example first rather than migrating your own business project at the start: get a hello_world-level app running on OpenHarmony, confirm the environment is sound, then add complexity layer by layer.
3. Core implementation of the accumulator: one codebase on three platforms
The accumulator's function is simple: a number in the center of the page and three operations, increment, decrement, and reset. I organized the code so the page and logic are somewhat separated, because if you later add a local database or network sync, an independent logic layer is much easier to extend. For state management I used the plainest setState without Provider or Riverpod, for a simple reason: the project's core is validating three-platform adaptation, not a state-management framework, and fewer variables make problems easier to locate.
This code renders essentially the same on Android and OpenHarmony. The one thing to watch: on OpenHarmony devices, abnormal Chinese font rendering is usually a missing system font library requiring engine-level configuration, which appeared on some early versions. On the latest 5.x version I tested, Chinese displayed normally without extra work.
My verification order was Android emulator first, then OpenHarmony real device, and finally iOS emulator. Why Android first? Because Flutter's debugging toolchain and Gradle ecosystem are most mature, with more complete error messages, so you can clean up business-code-level issues first. Then run OpenHarmony, focusing on platform shell, engine loading, and permission configuration issues absent on Android. Finally run iOS to confirm no platform-specific regressions. During verification I deliberately did one more thing: not a single 'if (Platform.isAndroid)' check appeared anywhere in the lib directory. Once such a check appears, the purity of reuse is insufficient and the design needs review.
4. Real problems and troubleshooting chain when building for OpenHarmony devices
When building on the OpenHarmony side I hit a fairly typical error. It looks frightening but is actually a mismatch between the Gradle configuration in the OpenHarmony project template and the registration method of newer Flutter Android plugins. New Flutter Android projects recommend declaring plugins uniformly in settings.gradle's pluginManagement and the app in the root build.gradle's plugins block, while the older OpenHarmony template might use an imperative form such as apply plugin: 'dev.flutter.flutter-gradle-plugin'.
Step one, look at the Android-side build.gradle to see what the new Flutter template looks like. Step two, compare whether the flutter plugin in the ohos project follows the same plugin-management logic. Step three, change the imperative apply in the ohos project to a plugins block declaration or vice versa, depending on the template's Gradle version. If a freshly generated template project throws this error, another possibility is that files from two projects were mixed, for example editing gradle files in the Android directory and then copying the configuration into ohos; OpenHarmony's native shell is an independent project and its Gradle configuration cannot be copied over, so you must modify the template's own copy.
The essence of this problem is that OpenHarmony's Flutter adaptation version and the upstream Flutter Android plugin update pace are not fully synchronized. The solution is not to memorize one writing style but to see which style the current Flutter version expects and align the template accordingly.
Installing an app on an OpenHarmony real device is a bit more troublesome than on Android. Android debugging can use the debug keystore directly, while OpenHarmony needs a debug certificate consisting of .p12, .cer, and .p7b files. The first time I ran 'flutter run -d' I could not see any OpenHarmony device in the list at all, because hdc did not recognize it properly or the device was not in developer mode. Enable developer mode and USB debugging on the device; use hdc to connect and confirm recognition; use automatic signing in DevEco Studio to generate a debug certificate, and if you do not configure the certificate in the ohos project's build-profile.json5 the built app will be refused installation on the device.
One reminder: the hdc command path differs from adb and may not be in Flutter's dependency directories but under DevEco Studio's SDK directory; if hdc is not found, configure PATH or use the full path. OpenHarmony's logging system is hilog, not logcat: when debugging Flutter, many dPrint outputs do not appear directly in the terminal and need hilog filtering, similar in思路 to 'adb logcat | grep flutter' on Android but with more monotone commands.
Hot reload works on OpenHarmony but occasionally fails compared with Android. For pure Dart code changes the r key works well; for native shell configuration or dependency changes a full restart is often needed. My suggestion is not to rely on hot reload as the default when doing OpenHarmony adaptation; if it does not work, just do a full build, which is often faster. Another debugging detail: after launching on a real device, if the page is blank, first check whether the inflated native app loaded the engine correctly; this is less common on the emulator because real devices have resource limits and occasionally show slow engine initialization, so distinguish a hang from a slow start.
After getting all three platforms running, I put together a daily-development efficiency comparison for reference. OpenHarmony's Flutter ecosystem is still in rapid flux, and many problems have no ready answer online, requiring you to reason by analogy from the Android side. At such times understanding the underlying mechanism matters far more than memorizing conclusions: if an error occurs at the engine layer, compare it with how the Android-side Flutter engine loads and you will often find a breakthrough.
The accumulator itself needs no system capabilities, but if you later build more complex apps on OpenHarmony you will certainly touch channel bridging. Calling the Harmony OS gallery or launching IAP payment, for example, are typical native capabilities where Dart only sends commands and the real work happens in ArkTS.
Once the accumulator ran, I also verified several common extension directions, with this conclusion: basic capabilities all work, differences are in details. Embedded database: the sqflite family runs on OpenHarmony, but note that native file paths are obtained differently from Android and must follow OpenHarmony's sandbox rules; for small amounts of local data you can also consider lightweight storage. Network requests: dio works normally on OpenHarmony; when capturing packets do not watch only the Android proxy, because OpenHarmony's HTTPS certificate trust logic may differ, so clarify certificate configuration during development or you may hit HTTPS handshake failures in production. Animation assets: lottie loading network zip packages also works, but mind the extraction path and app sandbox permissions, which are not the same as Android's cache directory.
All of this shows one thing: the core advantage of three-platform Flutter lies on the Dart side, but every platform has differences at its 'native edge,' and you cannot apply the same assumption to all. Finally, a personal takeaway: for OpenHarmony Flutter development, patience matters more than technical skill. Most environment-setup problems are version mismatches that take time to check, compare, and trial-and-error; once the environment works, writing business code feels little different from Android. If you are evaluating Flutter's feasibility in the Harmony OS ecosystem, I suggest starting with the simplest accumulator, getting it onto a real device, and personally experiencing the full flow from environment setup to build and deployment before deciding whether to invest in a larger project.