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: 拉取源码

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

### 步骤 2: 修改版本号

编辑 `pubspec.yaml`:

```yaml
# 修改前
version: 1.2.0

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

### 步骤 3: 项目引用

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

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

然后执行:

```bash
flutter pub get && flutter analyze --no-pub
```

### ✅ 完成！

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

---

## 四、原生插件适配流程

> 详细步骤请参考 [ohos平台适配flutter三方库指导.md](./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 必要配置

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