kitchen/packages/Flutter包鸿蒙适配通用指南.md

Flutter 包鸿蒙适配指南

文档创建: 2026-04-25 | 最后更新: 2026-04-25 适用对象: 所有需要在 HarmonyOS 上使用 Flutter 第三方包的开发者 核心原则: 纯Dart包零适配，原生插件需ets实现

---

一、核心结论（先看这个）

包类型	需要做什么	ohos目录
🟢 纯 Dart 包	仅改版本号后缀 -ohos.1	❌ 禁止创建！
🔴 原生插件	写 ets 原生代码 + DevEco Studio 打 har	✅ 必须有

⛔ 最重要的一条规则: 纯 Dart 包绝对不能创建 ohos/ 目录！ Flutter 引擎启动时会扫描所有 ohos 模块并 copyResource， 空壳模块引用不存在的 libs/flutter.har → 直接崩溃（错误码 9001005）。

---

二、如何判断包类型

2.1 快速判断

打开包根目录，检查以下三项：

├── 是否有 android/ 或 ios/ 目录？
│   ├── 无  → 🟢 纯Dart包 → 跳到第三章
│   └── 有  → 继续判断
│
├── pubspec.yaml 中是否有 flutter.plugin 配置？
│   ├── 无  → 🟢 纯Dart包（有平台目录但无插件声明）→ 跳到第三章
│   └── 有  → 🔴 原生插件 → 跳到第四章
│
└── 代码中是否使用了 MethodChannel / EventChannel / FFI？
    ├── 无  → 🟢 纯Dart包 → 跳到第三章
    └── 有  → 🔴 原生插件 → 跳到第四章

2.2 判断对照表

检查项	🟢 纯 Dart 包	🔴 原生插件
android/ 目录	❌ 无	✅ 有
ios/ 目录	❌ 无	✅ 有
flutter.plugin 声明	❌ 无	✅ 有
MethodChannel 使用	❌ 无	✅ 有
EventChannel 使用	❌ 无	✅ 有
FFI (dart:ffi) 使用	❌ 无	✅ 有
典型例子	fl_chart, badges, qr, mailer	mobile_scanner, file_picker, camera

2.3 常见纯 Dart 包类别

这些类型的包 100% 是纯 Dart，无需任何原生适配：

类别	代表包	说明
UI 组件	fl_chart, badges, card_swiper	纯 Widget 渲染
布局组件	staggered_grid_view	纯布局算法
图片处理	cached_network_image	网络+缓存（条件导入）
文本渲染	flutter_markdown	Markdown 解析+渲染
编码工具	qr (二维码生成)	纯算法实现
网络协议	mailer (SMTP)	Socket 通信
文档生成	docs_gee (DOCX/PDF)	字节流组装

---

三、纯 Dart 包适配步骤（3步搞定）

步骤 1: 拉取源码

cd packages
git clone --depth 1 --branch <版本号> <github地址> <包名>

步骤 2: 修改版本号

编辑 pubspec.yaml:

# 修改前
version: 1.2.0

# 修改后（添加 -ohos.1 后缀标识已适配）
version: 1.2.0-ohos.1

步骤 3: 项目引用

编辑项目根目录的 pubspec.yaml:

dependencies:
  <包名>:
    path: packages/<包名>

然后执行:

flutter pub get && flutter analyze --no-pub

✅ 完成！

就这么简单。不需要创建任何 ohos 文件，不需要写 Plugin.ets，不需要配置 module.json5。 Flutter 的 AOT 编译器会将纯 Dart 代码直接编译为各平台的机器码。

---

四、原生插件适配流程

详细步骤请参考 ohos平台适配flutter三方库指导.md

4.1 概览流程

1. flutter create --platforms ohos <plugin>_ohos     # 创建ohos模块骨架
2. 复制 android 版 lib/dart 代码，将 android 改为 ohos
3. DevEco Studio 编写 ets 原生代码（参考 android/ios 实现）
4. pubspec.yaml 添加 flutter.plugin.platforms.ohos 声明
5. DevEco Studio → Build → Make Module 打 .har 包
6. 确保 libs/flutter.har 存在（从其他已适配插件复制）
7. flutter create --platforms ohos example 创建验证工程
8. flutter run -d <device> 验证功能正常

4.2 关键文件清单

<plugin>/ohos/
├── Index.ets                          # 插件入口，export Plugin 类
├── oh-package.json5                   # 依赖声明，必须引用 libs/flutter.har
├── build-profile.json5                # 构建配置
├── libs/
│   └── flutter.har                    # ⚠️ 必须存在！Flutter引擎库
└── src/main/
    ├── module.json5                   # 模块声明，type: "har"
    ├── resources/base/profile/        # 资源配置
    └── ets/components/plugin/
        └── <PluginName>Plugin.ets      # 原生实现（MethodChannel Handler）

4.3 oh-package.json5 必要配置

{
  "name": "<plugin_name>",
  "version": "1.0.0",
  "description": "HarmonyOS implementation of <plugin>",
  "main": "Index.ets",
  "dependencies": {
    "@ohos/flutter_ohos": "file:libs/flutter.har"
  }
}

⚠️ libs/flutter.har 必须真实存在！否则编译通过但运行时闪退(9001005)。

---

五、⛔ 踩坑记录（血泪教训）

5.1 最严重: 给纯Dart包创建了空壳 ohos 目录

时间: 2026-04-25
错误: 为 9 个纯 Dart 包创建了空壳 ohos 目录（含 Index.ets、空壳 Plugin.ets 等）
现象: 鸿蒙端启动即闪退，无法进入任何页面
错误码: 9001005 (Invalid relative path)
堆栈: copyResource → startInitialization → checkLoader → setupFlutterEngine → onCreate

根因分析:

Flutter 引擎启动流程:
1. 扫描项目中所有含 ohos/ 目录的模块
2. 读取每个模块的 oh-package.json5
3. 解析 dependencies 中的 @ohos/flutter_ohos: "file:libs/flutter.har"
4. 尝试 copyResource 将 flutter.har 复制到应用沙箱
5. libs/flutter.har 不存在 → 9001005 崩溃

修复: 删除全部 9 个纯 Dart 包的 ohos 目录

预防:

在创建 ohos 目录之前，先确认：
✅ 该包是否真的有原生代码（MethodChannel/FFI）？
✅ 该包的 android/ios 目录下是否有真实的 Kotlin/Swift 实现？
如果都是 NO → 禁止创建 ohos 目录！

5.2 其他常见问题

问题	原因	解决方案
编译通过但运行闪退	ohos目录存在但 libs/flutter.har 缺失	从已适配插件复制 har 文件
analyze 报错找不到类	pubspec.yaml 中 pluginClass 配置错误	检查 dart 侧注册的类名
MethodChannel 无响应	ets 侧 handler 未正确注册	检查 onAttachedToEngine 中的 setMethodCallHandler
har 包体积过大	example/ohos 未删除	删除 example 下的 ohos 目录

---

六、检查清单（适配完成后逐项确认）

纯 Dart 包

• 已修改 version 后缀为 -ohos.1
• 没有 ohos/ 目录
• 没有 Index.ets / Plugin.ets / module.json5
• flutter pub get 通过
• flutter analyze --no-pub 通过

原生插件

• 已修改 version 后缀为 -ohos.1
• ohos/ 目录结构完整
• libs/flutter.har 文件真实存在（非空文件）
• oh-package.json5 正确引用 flutter.har
• module.json5 中 type 为 "har"
• Index.ets 正确 export Plugin 类
• ets 代码实现了 MethodChannel handler
• pubspec.yaml 中声明了 flutter.plugin.platforms.ohos
• DevEco Studio 编译 har 成功
• example 工程可正常运行

---

七、参考文档

文档	用途
ohos平台适配flutter三方库指导.md	原生插件完整适配流程（含截图和详细步骤）
[开发FFI plugin.md](./开发FFI plugin.md)	FFI 插件开发指南（C/C++ 原生库）
OpenHarmony应用如何集成Flutter模块.md	Flutter 模块集成到鸿蒙应用的架构文档
FlutterChannel通信.md	MethodChannel / EventChannel / BasicMessageChannel API 用法
本地已适配鸿蒙的库.md	本项目已适配的具体包清单和使用示例