欢迎光临
我们一直在努力

Flutter-OH 升级指导

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 版本应用编译 APIEngine 构建 APIDevEco 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 大版本内:

  • 更新 SDK 源码或切换到新 Tag;
  • flutter clean → flutter pub get;
  • 重新 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

    赞(0)
    未经允许不得转载:171主机测评 » Flutter-OH 升级指导
    分享到: 更多 (0)

    评论 抢沙发

    • 昵称 (必填)
    • 邮箱 (必填)
    • 网址