我最早在 Flutter 里做扫码功能,第一反应就是去 pub.dev 搜 qr_code_scanner,版本多、文档全、示例代码一跑就出画面,确实省心。直到我把同样一套代码迁移到 Flutter for OpenHarmony 上,才发现事情没那么简单:OpenHarmony 的相机接口、权限模型、原生插件机制跟 Android/iOS 完全是两套体系,qr_code_scanner 原版依赖的 Camera2 / AVFoundation 在鸿蒙设备上都不存在。
这篇文章不是教你怎么在安卓上扫码,而是记录我在 Flutter for OpenHarmony 工程里,把一个基于 qr_code_scanner 思路的二维码扫描能力从零跑通的全过程。包括 OpenHarmony 适配的底层差异、项目配置、桥接层设计、相机帧流转接、解码链路,以及我踩过的那些在 rk3568 / rk3588 开发板上特别典型的坑。准备在鸿蒙设备上用 Flutter 做扫码、工牌识别、设备绑定这类功能的同学,这篇文章可以直接当操作手册看。
1. 先搞清楚:Flutter for OpenHarmony 上的插件生态和安卓差在哪
1.1 Flutter for OpenHarmony 不是“换个包名”这么简单
很多人以为 OpenHarmony 兼容 Android APK,Flutter 应用打出来的 APK 直接丢上去就能跑,其实这个认识在消费级手机上有一定道理,但在 OpenHarmony 原生系统上并不成立。OpenHarmony 的应用开发接口是 ArkTS / ArkUI,底层渲染和系统服务都是自己的实现,Flutter 要跑在上面,必须通过 OpenHarmony 官方的 Flutter 适配分支来编译,最终产物是 HAP 包,不是 APK,也不是直接在 Android 运行时里兼容执行的。
Flutter for OpenHarmony 的适配工作在 OpenHarmony 官方仓库(flutter_flutter 的 ohos 分支)里已经做了不少,渲染能跑、基础 Widget 能显示、路由能跳、MethodChannel 也能用。但问题在于 Flutter 第三方插件的生态,绝大多数插件只实现了 Android 和 iOS 两端的原生代码,鸿蒙端没有对应实现。qr_code_scanner 就是非常典型的例子,它的 Android 端用 Camera2 API 管理相机和预览,iOS 端用 AVFoundation,OpenHarmony 这边既没有 Camera2 也没有 AVFoundation,所以原版插件在 OpenHarmony 工程里编译能过,但一调用相机就崩,或者干脆返回 NotImplemented。
1.2 qr_code_scanner 的插件分发机制决定了它需要“端口”
理解这个问题的关键,是搞清楚 Flutter 插件是怎么分发的。Flutter 插件本质上是一个 Dart 包加若干个原生工程目录,Android 的代码放在 android/,iOS 的代码放在 ios/,macOS、Windows、Linux 也各有自己的目录。Flutter 在构建时会读取插件的 pubspec,只把它对应平台的目录编译进产物。
OpenHarmony 不在 Flutter 官方支持的平台列表里,所以 pub.dev 上绝大多数插件都没有 ohos/ 目录。Flutter for OpenHarmony 的构建工具链为了兼容,会走一个类似“平台找不到就用 Android 实现”的兼容路径,但这里的实现是 Java/Kotlin 代码,OpenHarmony 原生模块是 ArkTS 的 .ets 文件加 native C++,两边的运行时互相不认。就算强行把 Android 源码编译进去,调用 CameraManager.openCamera 这类安卓 API 时也会直接抛异常,因为底层没有 Android Framework。
所以结论很直接:想在 Flutter for OpenHarmony 上用 qr_code_scanner,要么找别人已经移植好的 OpenHarmony 分支,要么自己照着它的接口设计写一套鸿蒙原生实现,通过 MethodChannel 桥接给 Dart 层调用。我这次采用的是后者,因为社区里针对 qr_code_scanner 的 OpenHarmony 移植版本还不太成熟,自己动手反而能把整个链路吃透。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 开发环境搭建:把 Flutter 工程从安卓切换到 OpenHarmony
2.1 工具链清单,一个都不能少
先说我最后跑通的环境,方便你对照:
- OpenHarmony 4.1 Release(RK3568 开发板)
- DevEco Studio 5.0.0(含 SDK 和 hvigor 构建工具)
- flutter_flutter 的 ohos 分支,版本基于 Flutter 3.22
- Dart SDK 3.4.0
- Node.js 18+(hvigor 需要)
这里有个重点:不能用 pub.dev 下载的 Flutter 官方 SDK 直接编译 OpenHarmony 应用。你需要在 gitee 上拉取 flutter_flutter 仓库,切换到 ohos 分支,然后用这个 SDK 来执行 flutter 命令。路径配置也简单,把 flutter/bin 加到 PATH,然后跑 flutter doctor,如果提示 OpenHarmony 相关环境信息,说明 SDK 分支切换成功。
而且版本匹配很关键。我在一开始用了比较老的 ohos 分支,结果 DevEco
