Flutter-OH 升级指导

欢迎大家 加入跨平台开发者社区。

适用于基于 OpenHarmony 适配的 Flutter 版本，帮助你在 鸿蒙 Flutter 项目 上做版本切换、迁移与日常维护。请按 当前版本 → 目标版本 对照执行。

---

阅读导航

章节	内容
一、版本与分支	支持的 OH 版本、分支、配套 API / DevEco
二、升级场景	小版本 / 大版本 / 跨平台
三、升级前准备	清单、拉取 SDK、环境变量
四、通用升级流程	doctor、清理、依赖、ohos、编译
五、分版本注意事项	3.35 / 3.32 / 3.27 / 3.22 等
六、跨平台迁移摘要	从纯 Android/iOS 工程接入 OH
七、问题与交流	Issue 入口

---

一、版本与分支

1. 当前常见 Flutter-OH 版本（示意）

具体以 flutter_flutter 仓库标签/分支为准，下表便于选型。

Flutter OH 版本	分支（示例）	状态	说明
3.7.12-ohos	dev	稳定	基于 Flutter 3.7.12
3.22.0-ohos	br_3.22.0-ohos-1.0.4	稳定	基于 Flutter 3.22.0
3.27.4-ohos	br_3.27.4-ohos-1.0.4	主推稳定	基于 Flutter 3.27.x 系适配，适合多数生产场景
3.32.4-ohos	oh-3.32.4-dev	预览	基于 Flutter 3.32.4，生产请评估
3.35.7-ohos	oh-3.35.7-dev	预览	跟进 Flutter 3.35 系，生产请评估

2. 配套关系

Flutter OH 版本	应用编译 API	Engine 构建 API	DevEco Studio
3.7.12-ohos	OpenHarmony API 18+	API 18+	5.1.0+
3.22.0-ohos	API 18+	API 20+	5.1.0+
3.27.4-ohos	API 18+	API 20+	5.1.0+
3.32.4-ohos	API 18+	API 20+	5.1.0+
3.35.7-ohos	API 18+	API 23+	6.0.0+

升级到 3.35.7-ohos 时，务必同步升级 DevEco 与 SDK API，避免编译或链接失败。

---

二、升级场景

• 小版本升级：同一大版本线下的 OH 补丁/构建号变化（如 3.27.4-ohos-1.0.x 之间）。
• 大版本升级：跨 Flutter 主版本（如 3.22 → 3.27 → 3.32），需重点看 Breaking Changes 与插件兼容。
• 跨平台迁移：原先只有 Android/iOS 的 Flutter 工程，首次接入 ohos 平台（与「升级 SDK」可合并规划）。

---

三、升级前准备

1. 检查清单

• 备份：工程目录、pubspec.yaml、pubspec.lock、自定义 ohos/ 改动（若有）。
• 环境：目标版本要求的 DevEco Studio、OpenHarmony / 鸿蒙 CLI/SDK。
• 官方变更：查阅 Flutter Release notes 与目标 OH 分支下的 changelog / breaking-changes 文档。
• 三方库：OpenHarmony 三方库兼容性列表（路径以仓库为准）。

2. 获取新版本 SDK

# 方式 A：直接克隆目标分支
git clone -b <目标分支名> https://gitcode.com/openharmony-tpc/flutter_flutter.git

# 方式 B：克隆后 checkout 指定 tag/分支
git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git
cd flutter_flutter
git checkout <版本 Tag 或分支>

# 示例：3.27.4-ohos 稳定线
git clone -b br_3.27.4-ohos-1.0.4 https://gitcode.com/openharmony-tpc/flutter_flutter.git

3. 环境变量（示例）

# Flutter-OH SDK
export FLUTTER_HOME=/path/to/flutter_flutter
export PATH="$FLUTTER_HOME/bin:$PATH"

# OpenHarmony SDK（按本机实际路径）
export OHOS_SDK=/path/to/ohos-sdk
export PATH="$OHOS_SDK/toolchains:$PATH"

# 国内镜像（按团队规范选用）
export FLUTTER_STORAGE_BASE_URL=https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com
export PUB_HOSTED_URL=https://pub.flutter-io.cn

---

四、通用升级流程

1. 验证环境

flutter doctor -v

预期包含 OpenHarmony toolchain 等与鸿蒙相关的通过项；若失败，先回到环境搭建文档排查。

2. 清理（按力度选用）

cd your_project

# 常规：清理当前工程构建产物
flutter clean

大版本切换或异常缓存时再考虑：

# ⚠️ 会清空全局 pub 缓存，影响本机所有 Flutter 项目，慎用
flutter pub cache clean

# ⚠️ 仅在你确认要重置当前 FLUTTER_HOME 对应 SDK 的引擎缓存时使用
# rm -rf "$FLUTTER_HOME/bin/cache"

3. 使用新 SDK 并确认版本

which flutter
flutter --version

4. 更新依赖

在 pubspec.yaml 中：

• 调整 environment.sdk / environment.flutter 以匹配目标 OH 版本；
• 将需原生支持的插件改为 OH 适配的 git 源或版本（见兼容性列表）；
• 执行：

flutter pub get

5. 鸿蒙工程（谨慎覆盖）

若从大版本升级或模板结构变化明显，可能需要对齐 ohos/：

# ⚠️ 可能覆盖你对 ohos 模板的自定义，执行前请提交/备份 git
flutter create --platforms ohos .

然后在 DevEco Studio 中打开 ohos/ 目录，检查 Signing Configs 等配置是否仍有效。

6. 编译与安装验证

flutter build hap --debug
flutter build hap --release

HAP 常见路径（以本机产物为准，可搜索 .hap）：

# 常见位置（相对 Flutter 项目根目录）
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 OH 大版本内：

1. 更新 SDK 源码或切换到新 Tag；
2. flutter clean → flutter pub get；
3. 重新 flutter build hap / flutter run 验证。

2. 大版本升级要点

目标版本	OH / 官方变更参考	备注
3.35.7-ohos	OH: 3.27 → 3.35 Breaking、Flutter 3.35	需 API 23+、DevEco 6+；插件对齐 3.35
3.32.4-ohos	Flutter 3.32	插件与 Dart 约束对齐 3.32
3.27.4-ohos	OH: 3.22 → 3.27、Flutter 3.27	当前常用稳定线之一
3.22.0-ohos	OH: 3.7 → 3.22 等说明、Flutter 3.22	渲染：Impeller-Vulkan 等默认策略与 3.7 差异大，需充分回归

若某分支下 changelog 路径调整，以仓库内 release-notes/changelog 实际文件名为准。

---

六、跨平台迁移摘要

从 仅 Android/iOS 的 Flutter 工程首次接入鸿蒙时，可与「升级到新 OH SDK」一起做。更细的步骤见：已有 Flutter 应用适配鸿蒙平台指导文档。

步骤	动作
1	备份工程
2	flutter create --platforms ohos . 或新建多平台工程
3	配置 pubspec.yaml（SDK 约束 + OH 兼容插件 git 源）
4	业务侧增加 Platform.isOhos 等分支（若需要）
5	自研插件在 ohos/ 侧补齐 ArkTS 实现
6	flutter run / flutter build hap

目录结构示意（非 JSON）：

your_project/
├── android/
├── ios/
├── ohos/                 # 新增
├── lib/
├── pubspec.yaml
└── ...

依赖示例（ref 以 flutter_packages 当前分支为准）：

dependencies:
  path_provider:
    git:
      url: "https://gitcode.com/openharmony-tpc/flutter_packages.git"
      path: "packages/path_provider/path_provider"
      ref: "br_path_provider-v2.1.5_ohos"

平台判断示例：

import 'dart:io';

if (Platform.isAndroid) {
} else if (Platform.isIOS) {
} else if (Platform.isOhos) {
  // OpenHarmony / 鸿蒙
}

---

七、问题与交流

• 框架 / 引擎：flutter_flutter Issues
• 官方插件适配：flutter_packages 各仓库 issue
• 示例与文档：flutter_samples / ohos/docs

---