已有 Flutter 应用适配鸿蒙平台指导文档
欢迎大家 加入跨平台开发者社区。
在已支持 iOS/Android 的项目中增加 ohos 平台目录，保持 Dart 业务代码多端复用。
适用场景
- 已有 Flutter 工程，希望 增量接入 OpenHarmony / 鸿蒙 NEXT（Flutter-OH）。
- 不打算新建工程，而是在 当前仓库 内补齐
ohos/与依赖、签名、构建流程。
前置条件
| 项 | 说明 |
|---|---|
| IDE | 已安装 DevEco Studio |
| Flutter-OH | 已按官方文档完成 Flutter OH 环境搭建（含 SDK、fvm/路径等） |
| 设备 | 真机或模拟器，且 hdc、flutter devices 能识别 ohos 设备 |
一、备份与添加鸿蒙平台
1. 备份现有项目（建议）
bash
cp -r your_flutter_project your_flutter_project_backup2. 为现有工程添加 ohos 平台
bash
cd your_flutter_project
# 在现有项目根目录执行，不要漏掉末尾的 .
flutter create --platforms ohos .成功后会出现 ohos/ 目录，与 android/、ios/ 并列。
3. 典型目录结构（示意）
text
your_flutter_project/
├── android/
├── ios/
├── ohos/ # 鸿蒙工程（新增）
│ ├── build-profile.json5
│ ├── hvigorfile.ts
│ ├── local.properties
│ ├── entry/ # 主入口模块
│ │ ├── build-profile.json5
│ │ ├── hvigorfile.ts
│ │ ├── oh-package.json5
│ │ └── src/main/
│ │ ├── ets/
│ │ │ ├── entryability/EntryAbility.ets
│ │ │ └── pages/Index.ets
│ │ └── resources/
│ └── ohos/ # Flutter 引擎相关模块（随模板生成）
├── lib/ # Dart 业务（多端复用）
├── test/
├── pubspec.yaml
└── ...说明 ：不同 Flutter-OH 版本模板细节可能略有差异，以你本地生成结果为准；核心是
ohos/entry与ohos根目录 的配置文件齐全。
二、配置签名
使用 DevEco Studio 打开项目中的 ohos 目录（打开该文件夹作为工程根，而非整个 Flutter 根目录）。
- File → Project Structure （部分版本为 Project → Signing Configs）
- 进入 Signing Configs
- 勾选 Automatically generate signature（自动生成调试签名）或按团队规范配置正式证书
- 保存（OK）
未正确配置签名时，flutter build hap 或安装阶段容易失败。
三、适配 pubspec.yaml
1. 环境与 Flutter 约束
按你所用的 Flutter-OH 发行版 调整 environment，例如：
yaml
# 示例：Flutter 3.27.x-ohos
environment:
sdk: '>=3.0.0 <4.0.0'
flutter: ">=3.27.0"
yaml
# 示例：Flutter 3.35.x-ohos
environment:
sdk: '>=3.0.0 <4.0.0'
flutter: ">=3.35.0"注意 ：
flutter下限应 ≥ 当前实际使用的 OH 引擎版本 ，并与团队 CI 一致；具体以 官方发布说明 / CHANGELOG 为准。
2. 拉取依赖
bash
flutter clean
flutter pub get四、三方库适配
适配前请先查阅：
若依赖未适配，可到社区跟踪进度或向 flutter_flutter issues 反馈。
1. 使用 OpenHarmony 适配分支（Git 依赖示例）
将 带原生实现的插件 从 pub.dev 默认源改为 openharmony-tpc 等维护的 git 路径，ref 需按仓库实际分支/标签调整：
yaml
dependencies:
# path_provider 示例（ref 请对照官方文档当前推荐分支）
path_provider:
git:
url: "https://atomgit.com/openharmony-tpc/flutter_packages.git"
path: "packages/path_provider/path_provider"
ref: "br_path_provider-v2.1.5_ohos"
shared_preferences:
git:
url: "https://atomgit.com/openharmony-tpc/flutter_packages.git"
path: "packages/shared_preferences/shared_preferences"
ref: "br_shared_preferences-v2.5.4_ohos"
url_launcher:
git:
url: "https://atomgit.com/openharmony-tpc/flutter_packages.git"
path: "packages/url_launcher/url_launcher"
ref: "br_url_launcher-v6.3.2_ohos"2. 纯 Dart 包
无平台通道、仅 Dart 实现的包，多数 无需改源码 即可在 ohos 上随 Flutter 运行；若依赖了未适配的原生插件，仍需按上节替换。
3. 自研 Plugin
需为插件增加 ohos 平台实现，可参考：
4. 平台判断代码
在 Flutter-OH 提供的 dart:io 扩展下，可使用 Platform.isOhos。若原有逻辑只区分 Android / iOS，请补上鸿蒙分支：
dart
import 'dart:io';
if (Platform.isAndroid) {
// Android
} else if (Platform.isIOS) {
// iOS
} else if (Platform.isOhos) {
// OpenHarmony / 鸿蒙
}说明 ：
Platform.isOhos依赖 Flutter-OH SDK；纯官方 Flutter 不含此项，请在 OH 工具链下编译运行。
五、构建与运行
1. 确认设备
bash
flutter devices示例（示意）：
text
9CN0123608000xxx (mobile) • ohos-arm64 • Ohos OpenHarmony-x.x.x2. 运行调试
bash
flutter run -d <device_id>
# 仅一台鸿蒙设备时可简写
flutter run3. 构建 HAP
bash
flutter build hap --debug
flutter build hap --release4. 安装 HAP
常见产物路径 （以当前工具链为准，若与本地不一致请在 ohos/entry/build/... 下搜索 .hap）：
bash
# 典型路径（相对 Flutter 项目根目录）
# ohos/entry/build/default/outputs/default/entry-default-signed.hap使用 hdc 安装（macOS / Linux 用 /，Windows 可将路径改为反斜杠）：
bash
hdc install ohos/entry/build/default/outputs/default/entry-default-signed.hap
# 多设备时指定序列号
hdc -t <device_id> install ohos/entry/build/default/outputs/default/entry-default-signed.hap六、检查清单（小结）
| 步骤 | 动作 |
|---|---|
| 1 | flutter create --platforms ohos . |
| 2 | DevEco 打开 ohos/，配置 Signing |
| 3 | 调整 pubspec.yaml 的 environment 与 git 版插件 |
| 4 | flutter pub get，处理编译报错与缺失插件 |
| 5 | 代码中补充 Platform.isOhos 等分支（如有） |
| 6 | flutter run / flutter build hap + hdc install |
相关文档
- Flutter-OH 示例与文档：flutter_samples / ohos/docs
- 引擎与版本变更：flutter_flutter
文档随 Flutter-OH 版本演进，命令与路径请以你本地 SDK 及官方最新说明为准。