最近在把一个内部代号叫 Books 的电子书阅读应用从 Android 往鸿蒙系统上迁移，过程比我预想中要“热闹”得多。Flutter 跨平台开发在 Android 和 iOS 上已经非常顺滑，但鸿蒙并不是 Flutter 官方支持的目标平台，这意味着“跨平台”三个字到了鸿蒙上先得打个问号。我最初以为只要把 Dart 代码原封不动编译一遍就能出包，结果光环境适配就折腾了两天。这篇文章把 Books 在鸿蒙上的完整适配过程、踩过的坑、以及现在跑通的方案都整理出来，给同样想用 Flutter 去碰鸿蒙的团队一个参考。
如果你是那种想“一套代码全端跑”的 Flutter 开发者，或者正在评估公司现有 Flutter 项目要不要接入鸿蒙，这篇东西应该能帮你省下不少时间。文中涉及的知识点包括 Flutter 的环境安装与配置、鸿蒙工程改造、内嵌数据库选型、网络抓包调试、登录支付对接、打包签名，以及 Flutter 产物反编译防护。我会尽量说清楚“为什么这么做”，因为鸿蒙生态和 Android/iOS 的思路差别，比很多人想象中大得多。
1. 鸿蒙上的 Flutter 到底怎么跑起来：环境与工程模板调整
1.1 先把认知对齐：Flutter 官方并不直接支持鸿蒙
先说一个很多人容易忽略的事实：你在 pub.dev 上看到的绝大多数 Flutter 插件，官方并没有为鸿蒙做过适配。Flutter 官方支持的桌面端、移动端平台里没有鸿蒙这一项，目前能跑在鸿蒙上的 Flutter，主要靠 OpenHarmony 社区维护的 flutter_flutter 分支，以及一票热心开发者移植的插件。
Books 这个应用本身是一个典型的阅读器，核心功能包括书库管理、EPUB/PDF 阅读、阅读进度同步、会员付费。从技术栈看，它不算复杂，Dart 代码里大部分是界面渲染和数据调度。可一旦进入鸿蒙，你首先面对的不是“写代码”的问题，而是“这套东西能不能编译成鸿蒙认识的文件”的问题。鸿蒙 NEXT 上市以后，应用市场里上架的包基本是 HAP 格式，不再兼容 APK，所以简单拿安卓包硬塞进去这条路已经堵死。
理解了这一点，你就明白为什么要把“鸿蒙适配”当成一个独立工程来做，而不是在现有 Android 工程上打几个补丁。Books 的迁移路径是：Flutter 代码保持不动或尽量少动，但构建目标里多出一个 ohos，最终产出 HAP 包；涉及原生能力的插件则逐个排查，能换纯 Dart 实现就换，换不了就走鸿蒙原生 MethodChannel。
1.2 环境准备：版本配对比想象中更挑
Books 的迁移是从一套干净环境开始的。我强烈建议不要在自己日常开发机里直接改配置，因为 Flutter 鸿蒙分支和官方 Flutter 版本的目录结构有差异，共用一个 SDK 容易把两边都搞坏。
我的做法是单独拉取 openharmony-sig/flutter_flutter 仓库到独立目录，把它当作鸿蒙专用的 Flutter SDK。版本上我选了比较稳定的 3.x 系列，配合 DevEco Studio 5.x 和对应的 HarmonyOS SDK，整体配合还算顺滑。
下面是我实际使用的环境清单，可以照抄：
| 组件 | 推荐版本/来源 | 用途 |
|---|---|---|
| DevEco Studio | 5.x（带 HarmonyOS SDK） | 鸿蒙原生工程开发与签名 |
| HarmonyOS SDK | API 12 或更高 | 编译 HAP 所需系统库 |
| ohpm | 随 DevEco 安装 | 管理鸿蒙原生依赖（类似 pub） |
| hvigor | 随 DevEco 安装 | 鸿蒙工程构建工具 |
| Flutter 鸿蒙分支 | openharmony-sig/flutter_flutter | 提供 ohos 构建目标 |
| Flutter 官方 SDK | 原版本（另目录） | 继续维护 Android/iOS |
环境变量方面，先把鸿蒙 Flutter SDK 的 bin 目录加到 PATH 里，然后运行 flutter doctor 看看识别情况。注意，修改 PATH 之后一定要开一个新的终端窗口，我在“flutter sdk 安装”“path 需要新终端生效”这两个问题上浪费了不少时间，旧终端里敲 flutter 永远指到老版本。
如果环境里还有 Android 构建需求，ANDROID_HOME 也别删。鸿蒙工程虽然不依赖 Gradle，但 Flutter 工具链的某些公共逻辑仍然会读取 Android SDK 路径。Books 团队里同时存在 Android 和鸿蒙两条产物流水线，我就是让它们共用一个 HOME 目录，按命令区分构建目标。
1.3 Books 项目迁移的第一个大坑：Gradle 插件报错
迁移 Books 时遇到的第一个报错，标题是“you are applying flutter's main gradle plugin imperatively using the apply method”。这条报错在所有 Flutter 高版本项目中很常见，原因是 Flutter 官方把 Gradle 插件推荐用法从“在 build.gradle 里直接 apply”改成了“在 settings.gradle 里用 pluginManagement 和 plugins 块声明式加载”。如果你还沿用老式写法，只要环境里 Gradle 版本够新，构建就会直接拒绝执行。
鸿蒙 Flutter 分支在生成工程模板时，有时候会把 Android 和鸿蒙两套构建脚本一起生成，CI 里如果先触发 Gradle 检查，这条报错会立刻跳出来。解决办法是把项目迁移到新的声明式写法：
// settings.gradle pluginManagement { def flutterSdkPath = { def properties = new Properties() file("local.properties").withInputStream { properties.load(it) } def flutterSdkPath = properties.getProperty("flutter.sdk") assert flutterSdkPath != null, "flutter.sdk not set in local.properties" return flutterSdkPath }() includeBuild("$flutterSdkPath/packages/flutter_tools/gradle") repositories { google() mavenCentral() gradlePluginPortal() } } plugins { id "dev.flutter.flutter-plugin-loader" version "1.0.0" id "com.android.application" version "8.1.0" apply false id "org.jetbrains.kotlin.android" version "1.8.22" apply false }然后把原来 app/build.gradle 里的apply plugin:那几行删掉，替换成 plugins 块：
plugins { id "com.android.application" id "kotlin-android" id "dev.flutter.flutter-gradle-plugin" }改完同步一下 Gradle，原本的报错就消失了。
Books 真正的鸿蒙工程目录是在 DevEco Studio 里单独创建的。鸿蒙侧使用的是 hvigorfile.ts，不是 Gradle 文件，负责把 Flutter 编译出来的 so 库、assets 资源包组装成 HAP。你可以把它理解成“Flutter 负责生成零件，hvigor 负责组装整车”。如果没有特殊原因，直接用社区脚手架生成鸿蒙壳工程，再把 Books 的 Dart 源码路径指过去，是最快的方式。
2. Books 书库的鸿蒙改造：数据库、本地文件与图书渲染
2.1 本地书库选型：从 sqflite 到纯 Dart 方案
Books 这类阅读应用，数据层核心是书籍元信息、阅读进度、书签、书架排序。Android 版本我用了 sqflite，表格结构简单清晰，但在鸿蒙分支上 sqflite 不可用。原因不复杂：sqflite 底层依赖 Android 系统提供的 SQLite，鸿蒙上根本没有这套 Java API，插件一调用原生方法就崩。
数据库选型时我比较了三条路线：
- 继续用 SQLite 系，比如 drift。drift 本身是纯 Dart 的，但底层仍然依赖 sqlite3_flutter_libs 来提供原生 so 库。鸿蒙上这个库没有官方预编译包，要么自己用 OpenHarmony 交叉编译环境编一份，要么找社区产物。你能编译成功，性能确实不错，但对普通团队来说维护成本偏高。
- 使用 HarmonyOS 原生提供的 RelationalStore（关系型数据库），再通过 MethodChannel 暴露给 Flutter 调用。可靠，但数据库操作全要自己封装一层 bridge，工作量大。
- 换纯 Dart 实现的数据库。我最终选了 sembast。它把数据存成文件，没有原生依赖，天然跨平台，在鸿蒙上能直接跑。Books 的书库量级是几百本到几千本，完全够用，不用上重量级 SQLite。
Books 的书库模型我简化成下面这种结构：
class Book { final String id; final String title; final String author; final String coverPath; final String filePath; final double progress; final int lastReadAt; final Map<String, dynamic> metadata; }打开时用 sembast 的 intMapStoreFactory.store('books') 存业务字段，阅读进度和书签单独建 store。启动流程就三步：打开数据库、读取书架列表、恢复上次阅读位置。整个过程不涉及任何原生调用，鸿蒙和 Android 上逻辑完全一致，这是纯 Dart 数据库最大的好处。
2.2 导入图书与封面图库：调用鸿蒙原生选择器
Books 的图书来源主要是本地导入，用户需要从文件管理器挑 EPUB/PDF，或者从相册选封面。Flutter 常用的 file_picker、image_picker 插件在鸿蒙上并没有官方实现，社区虽然有一些 fork，但功能和使用体验差异很大。Books 的选择是自己封装原生 Channel，这样最可控。
核心做法是在鸿蒙工程里注册一个 MethodChannel，名字叫books/file，Flutter 端发起pickFile、pickImage两个调用：
const channel = MethodChannel('books/file'); final Map<String, dynamic>? result = await channel.invokeMethod('pickFile', {'type': 'epub,application/pdf'}); if (result != null) { final String path = result['path']; final String displayName = result['displayName']; // 复制到应用沙箱目录 }鸿蒙原生侧用系统文件选择器拉起 DocumentPicker/PhotoViewPicker，拿到文件 URI 后拷贝到应用沙箱，再把后续可访问的路径返回给 Flutter。这里有一个容易踩的坑：直接拿返回的临时 URI 去读文件，可能只有当次启动有效，杀掉进程后权限会失效。安全做法是第一时间把文件复制进应用目录，之后只使用沙箱路径。
权限方面，鸿蒙的权限模型类似 Android 的运行时权限。读取图库需要ohos.permission.READ_MEDIA，文件管理器方式通常不需要额外声明存储权限，但首次跳转会弹窗，体验上要比 Android 简单。Books 的导入流程在鸿蒙上比 Android 还顺一些，系统级选择器返回的文件信息比较完整。
2.3 EPUB/PDF 渲染：与其适配插件，不如把渲染丢给原生 WebView
阅读器的核心是渲染 EPUB 和 PDF。这两类文件在 Flutter 社区本来就没有特别统一的跨端方案，Android 上我会用 pdfx 渲染 PDF，EPUB 则解析出来转 HTML 后用 webview_flutter 展示。鸿蒙适配时，我发现这些插件都存在兼容性风险，与其花大力气去调插件，不如直接用鸿蒙原生 WebView 承载内容，Flutter 只负责导航和 UI 壳。
Books 的做法是：EPUB 用 Dart 端解析，解压出文本和章节结构，生成干净的 HTML 内容；PDF 直接给原生 WebView 一个文件路径让它自己渲染。Flutter 与原生之间仍然走 MethodChannel，控制加载、翻页、缩放，以及返回阅读进度。
为什么这么做？webview_flutter 在鸿蒙上虽然有社区适配，但能力边界不明确，很多 PDF 在线预览、下载回调之类的功能需要额外验证。而鸿蒙的 Web 组件本身就是系统能力，对 EPUB 拆分出来的 HTML 和原生 PDF 渲染支持都很好，稳定性高得多。Books 阅读器切换成“Flutter 壳 + 原生 WebView 核心”之后，页面卡顿和字体错乱的问题基本消失，代价是阅读器这一块不能完全跨端，必须为鸿蒙维护一套独立通道。
3. 联调期最容易翻车的三件事：Dio 网络、微信登录与支付
3.1 Dio 能跑，但证书和抓包要提前铺好
Books 的账号系统和阅读进度同步依赖后端接口，Flutter 端用的是 Dio。好消息是 Dio 的 Dart 层实现并不依赖特定原生平台，底层 Http 能力由 dart:io 提供，鸿蒙的 Flutter 分支把这一层也适配了，所以网络请求基本开箱即用。
容易忽略的是权限。鸿蒙应用必须在 module.json5 里声明ohos.permission.INTERNET，否则所有请求都会秒失败。这个错误在日志里往往不明显，HTTP 层直接超时，我第一次排查花了半个多小时。
联调阶段绕不开抓包。这里把“flutter dio 如何抓包”的实操步骤统一写一遍：
- 手机和电脑连同一个局域网，手机 Wi-Fi 设置里把代理指向电脑 IP 和抓包工具监听端口（比如 Charles 的 8888）。
- 在电脑端安装 Charles 或 mitmproxy 的根证书，然后让手机下载并安装该证书。
- 鸿蒙新版系统对用户 CA 证书限制较严，Debug 包需要配置网络安全信任，允许调试场景信任用户证书；Release 包保持默认，不要开信任所有证书。
- 用 Dio 时，如果发现 HTTPS 请求报证书错误，可以先确认真机时间和证书时间是否一致，再考虑在 Debug 模式下临时加 badCertificateCallback。
if (kDebugMode) { httpClientAdapter = IOHttpClientAdapter() ..createHttpClient = () { final client = HttpClient(); client.badCertificateCallback = (cert, host, port) => true; return client; }; }上面这段代码被很多人直接复制到生产环境，我觉得需要强调：它只应该出现在 Debug 分支。Books 在 Release 包里严格保留系统默认证书校验，否则用户数据会暴露在中间人攻击风险下。
3.2 微信登录：绕开纯 Flutter 插件，直接走原生 Channel
Books 之前用的是软件包市场上比较常见的微信登录 Flutter 插件，这些插件底层对接的是 Android/iOS 微信 SDK。鸿蒙上微信提供的是 HarmonyOS 版本 SDK，接口完全不一样，继续用老插件不仅登录拉不起来，在部分设备上还会引起崩溃。
最终方案是封装自己的登录 Channel，原生侧在鸿蒙工程中调用微信 HarmonyOS SDK，注册 AppID，发起登录请求，接收回调，再把 code 或 token 返回给 Flutter：
const channel = MethodChannel('books/auth'); final Map<String, dynamic>? result = await channel .invokeMethod('wechatLogin', {'appId': 'wxYourAppId'});鸿蒙原生侧需要在对应 UIAbility 的 onAcceptWant 回调里处理微信返回的授权结果，然后把 success/error 信息传回 Flutter。整个过程并不复杂，但它要求团队里有懂鸿蒙原生开发的人。如果你想完全靠 Flutter 插件解决社交登录，目前还没有完美的选择。
这里顺带提一个热搜里出现的现象：“鸿蒙系统钉钉浏览器 SSO 登录白屏”。这种现象在 WebView 内嵌第三方登录页时很容易遇到，多半不是鸿蒙系统的问题，而是切换 WebView 内核后 UA 标识变了，对方服务端无法识别，或者页面里的 JavaScript 桥没有注入。Books 在某次对接 H5 登录页时也出现白屏，排查下来是鸿蒙 WebView 默认关闭了 DOM Storage，H5 脚本一执行就报错，界面自然空白。在原生 WebView 配置里把 javaScriptEnabled 和 domStorageEnabled 都打开，同时设置一个包含 HarmonyOS 标识的自定义 UA，问题就消失了。
3.3 会员与购买：接 HMS IAP 而不是原来的支付渠道
Books 的收入来源是会员订阅和单本购买。Android 端原本接的是 Google Play Billing 或者其他第三方聚合支付，鸿蒙上架华为应用市场后，这些渠道全部失效，必须接入 AppGallery Connect 的应用内支付（IAP）。
华为官方提供了 huawei_iap 插件，虽然叫“Huawei IAP”，但可以理解成 Flutter 侧的封装，底层走的是鸿蒙原生支付能力。接入时需要注意几件事：
- 在 AGC 后台创建应用，配置签名证书指纹，开通“应用内支付”服务。
- 创建商品 ID，区分消耗型商品（单本购买）和订阅型商品（会员包月/包年）。
- 客户端初始化 IAP，拉起商品查询，再发起购买。
- 购买结果的票据校验必须放到服务端，不能只信任客户端返回的 local data。
一个比较隐蔽的坑是测试账房配置：如果你没有在 AGC 后台添加测试账号，购买流程会在支付前弹出一个“环境异常或账号未验证”之类的错误。Books 在联调时就卡在这里，加上测试账号后，沙箱支付环境立刻通了。另外，IAP 商品状态修改后需要重新发版才生效，商品信息有缓存，经常出现“后台改了名字，客户端还是旧名称”的现象，不要太惊讶。
支付回调的可靠性也需要关注。鸿蒙侧支付结果回调可能延迟，Flutter 端不要一收到失败就立刻关闭订单页面，最好加一个轮询或等待机制，等服务端最终确认。Books 的做法是购买成功后先显示“处理中”，等服务端回调验票成功，再刷新会员状态。
4. 从 HAP 到上架：构建签名、真机安装与 Flutter 反编译风险
4.1 用 hvigor 构建 HAP，签名文件要认清楚
Books 最终要产出 HAP 上传应用市场，鸿蒙侧的构建工具是 hvigor，命令行入口是 hvigorw。编译 Flutter 鸿蒙包的过程和 Android 略有不同，大致是先用鸿蒙 Flutter 分支编译出libapp.so、libflutter.so和flutter_assets，再由 hvigor 把它们组装进 HAP 包。
签名环节是很多新手绕不过去的坎。鸿蒙签名文件主要有三个：.p12（密钥库）、.cer（证书文件）、.p7b（Profile 文件）。打开 build-profile.json5，把这三项配置进去，就可以自动签名：
"signingConfigs": [ { "name": "default", "type": "HarmonyOS", "material": { "certpath": "./sign/certificate.cer", "storePassword": "******", "keyAlias": "debugKey", "keyPassword": "******", "profile": "./sign/profile.p7b", "signAlg": "SHA256withECDSA", "storeFile": "./sign/keystore.p12" } } ]建议把签名文件统一放一个目录，不要提交到 Git 仓库。Books 的 CI 机器配置了不同的签名路径，本地打包用 debug 证书，发布包用 release 证书，这一点和 Android 双签名机制很像。
4.2 真机安装与调试：hdc 命令比 IDE 更快
用 DevEco Studio 调试鸿蒙应用很方便，但在 CI 环境或命令行场景，hdc 是更趁手的工具。hdc 类似 Android 的 adb，常用命令不多，我整理了一下：
hdc list targets # 查看连接的设备 hdc install app.hap # 安装 HAP 包 hdc uninstall com.example.books # 卸载 hdc shell hilog # 查看应用日志真机调试时如果遇到安装失败，最常见的错误是签名不一致。DevEco 调试签名只在特定设备上生效，换一台新设备就要重新添加 UDID 并生成调试证书。另一个常见坑是 API 版本过低，Books 初期用了一个比较老的 HarmonyOS SDK 编译测试包，手头测试机系统版本比较高，安装时报错“signature verification failed”，升级 SDK 后解决。
模拟器能覆盖大部分 UI 场景，但涉及 IAP、华为账号登录这些系统级能力时，模拟器的返回结果和真机差别很大，容易造成“模拟器能付、真机付不了”的怪象。凡是支付和登录相关功能，Books 都会强制在真机上回归一轮。
4.3 反编译风险：Flutter 产物在鸿蒙上同样能被人逆向
说到 Flutter 安全，很多人有个误解，认为 AOT 编译后 Dart 代码就变成机器码了，别人反编译不了。实际上，Flutter 的 AOT 产物并非完全安全。现在社区里已经出现针对 Flutter AOT snapshot 的逆向工具链，比如 blutter、reFlutter 这一类，它们可以还原 Dart 堆快照、恢复符号名，甚至定位到具体逻辑分支，这在“反编译 Flutter”这个热搜词下面讨论得很激烈。
Books 做的是内容付费，图书正文就是核心资产，所以防逆向这件事必须认真对待。我的防护清单大致如下：
- 构建时加
--obfuscate --split-debug-info=build/symbols，混淆 Dart 符号，同时把调试符号文件单独归档，不放进安装包。 - 敏感字符串不要明文写在 Dart 代码里。API Key、加密密钥等运行时拼接或从服务端下发，最少也要做一层字节混淆。
- 核心逻辑尽量下沉。内容解密、票据校验这些敏感操作放到鸿蒙原生层（ArkTS/C++），Dart 层只负责展示，逆向者拿到的只是一层皮。
- 图书文件在设备上加密存储，密钥存放在服务端或安全硬件区，解密只在内存中进行，避免直接落盘明文。
- 网络传输层启用证书校验，不允许随便改 endpoint。
把--obfuscate加进构建命令很简单，但要注意一个副作用：混淆后错误日志里的函数名会变成不可阅读的短符号，调试 Release 包问题会变困难。所以 Books 的 CI 会把混淆后的 symbols 文件按版本号归档，出问题对照符号文件来还原堆栈。这是个容易被忽略但很重要的习惯。
还有一个细节：鸿蒙侧原生的 ArkTS 代码默认也会被打包成字节码，同样存在反编译风险。敏感算法放到 C++ 层，并用系统能力做密钥保护，比单纯写在 ArkTS 里安全得多。Books 的章节加密、离线授权校验都遵循这个原则。
我在这次迁移里最大的体会是：Flutter 在鸿蒙上的适配正在逐步变好，但千万别把它想象成“把 target 一换就完事”。数据库、网络、登录、支付、逆向防护，每一块都要重新审视一次。尤其是 Books 这种依赖原生能力和内容版权的应用，花在鸿蒙工程上的时间不会比写 Flutter 代码少多少。好消息是，一旦把数据库和网络这两条主干跑通，剩下的插件适配问题都能找到替代方案，整个工程的可维护性还是比较乐观的。
