Flutter 项目鸿蒙适配实战：从环境搭建到多环境打包全指南

2026 年，Flutter 与鸿蒙系统的兼容性已从技术验证走向工程化落地。本文基于最新的 Flutter-OH 3.35.7 版本和 CPF-Flutter 生态，带你完整走一遍 Flutter 项目鸿蒙适配的全流程。

一、背景：Flutter 鸿蒙化走到哪了？

先说说大背景。2026 年 1 月，OpenHarmony 正式成立了 Flutter SIG 工作组，统筹推进 Flutter 鸿蒙化的技术迭代和生态建设。随后在 3 月正式发布了 Flutter 3.35 Release 版本，除了全量适配上游社区特性外，还在性能负载等方面做了深度优化。

生态层面也有大动作。2026 年 6 月，官方在 AtomGit 平台搭建了 CPF-Flutter 专属组织，将原本分散在 openharmony-tpc、openharmony-sig 等多个组织下的核心引擎、SDK 和 124 个三方插件库全部集中迁移到了统一的新组织下。这意味着过去那种"找仓库像大海捞针"的日子终于结束了。

版本现状 ：目前官方 Flutter 已到 3.44，但鸿蒙只适配到 3.35.7，所以不能直接用最新版跑鸿蒙，必须切到鸿蒙定制版。

二、环境准备

2.1 下载鸿蒙适配版 Flutter SDK

bash 复制代码

git clone https://atomgit.com/CPF-Flutter/flutter_flutter.git

注意：由于 2026 年 6 月的仓库大迁移，原来 openharmony-tpc 下的仓库已迁移至 CPF-Flutter 组织，请使用新地址。

2.2 安装 DevEco Studio

推荐使用 DevEco Studio 6.0.2 Release 及以上版本。

2.3 配置环境变量

bash 复制代码

# HarmonyOS SDK 路径
HOS_SDK_HOME=/path/to/DevEcoStudio/sdk

# Flutter 镜像（国内加速）
FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
PUB_HOSTED_URL=https://pub.flutter-io.cn

# Flutter 鸿蒙版 bin 目录加入 PATH

2.4 关联 Flutter 与鸿蒙 SDK

bash 复制代码

flutter config --ohos-sdk="/path/to/DevEcoStudio/sdk"
flutter doctor -v

如果遇到 NoHmosSDKfound 报错，核心原因是环境变量缺失或 Flutter 未正确识别鸿蒙 SDK 路径，按上述步骤配置即可解决。

三、生成鸿蒙原生项目组件

3.1 查看项目名称

找到 pubspec.yaml 中的 name 字段，记下 project_name。

3.2 创建鸿蒙平台工程

bash 复制代码

# 只创建 ohos 平台（推荐）
flutter create --platforms ohos project_name

# 或者创建多平台（android + ios + ohos）
flutter create project_name

关于创建方式，官方推荐使用 --platforms ohos 只生成鸿蒙平台，避免引入不必要的平台代码。

3.3 拷贝 ohos 目录

将生成的 ohos/ 目录拷贝到原 Flutter 项目中。

3.4 统一包名

修改 ohos/ 中的 bundleName，确保与 Android 和 iOS 的包名保持一致。

四、三方插件适配

4.1 查找已适配的插件

过去需要在 Gitee 的 openharmony-sig 仓库里翻找，现在可以直接访问 CPF-Flutter 组织主页：atomgit.com/CPF-Flutter。

目前官方已完成 39+ 主流插件的全版本适配，涵盖网络、存储、相机、音视频、路由、权限、UI 动画等高频开发组件，支持 Flutter 3.7、3.22、3.27、3.35、3.41 多版本适配。

4.2 在 pubspec.yaml 中引用

由于鸿蒙适配的插件并非通过 Pub.dev 发布，需要通过 Git 方式引入：

yaml 复制代码

dependencies:
  # 方式一：通过 Git 引入（推荐）
  path_provider:
    git:
      url: "https://atomgit.com/CPF-Flutter/flutter_packages.git"
      path: "packages/path_provider/path_provider"
  
  # 方式二：如果插件已发布到 pub.dev 且支持 ohos
  shared_preferences: ^2.2.2

4.3 判断插件是否需要适配

并非所有插件都需要适配。判断逻辑很简单：

检查 pubspec.yaml ：看是否有 android、ios 等平台原生实现配置
检查 Dart 代码 ：是否包含 Platform.isAndroid、MethodChannel 等平台逻辑
纯 Dart 库无需适配，只有含平台逻辑的库才需要

4.4 常见组件替换案例

原文档中提到的 extended_image 无法适配，替换为 photo_view。这属于典型的纯 UI 组件替换方案------如果某个插件没有鸿蒙适配版本，可以找功能相近的纯 Dart 组件替代。

五、多环境打包适配

5.1 Flutter 端配置

在 pubspec.yaml 中引入：

yaml 复制代码

dev_dependencies:
  flutter_flavorizr: 2.1.6

配置 flavors：

yaml 复制代码

flavors:
  env_release:
    app:
      name: "正式版"
  env_test:
    app:
      name: "测试版"

ohos:
  bundleName: "com.example.app"

注意：环境名称不要使用 release、dev、uat 等关键字，会报错。

5.2 鸿蒙端配置

鸿蒙的多环境机制与 Android/iOS 有本质差异：

维度	Android	iOS	HarmonyOS
构建系统	Gradle	Xcode	hvigor
多环境机制	productFlavors	scheme	product + target
配置格式	Groovy/Kotlin DSL	.xcodeproj	JSON5

修改项目级配置 ohos/build-profile.json5：

json5 复制代码

{
  "app": {
    "products": [
      {
        "name": "default",
        "signingConfig": "default"
      },
      {
        "name": "env_release",
        "signingConfig": "release"
      }
    ]
  }
}

修改模块级配置 ohos/entry/build-profile.json5：

json5 复制代码

{
  "targets": [
    {
      "name": "default",
      "applyToProducts": ["default"]
    },
    {
      "name": "release_target",
      "applyToProducts": ["env_release"]
    }
  ]
}

关键点 ：build-profile.json5 中的 product.name 必须与 flutter run --flavor 传入的 flavor 名完全一致，否则会静默回退到 default。

5.3 运行与打包命令

运行（调试） ：

bash 复制代码

flutter clean
flutter run --flavor=env_test --dart-define=ENVIRONMENT=test --debug

打包：

bash 复制代码

flutter build hap --flavor=env_release --dart-define=ENVIRONMENT=prod --release

Flutter for OpenHarmony 提供了专门的构建命令，将 Dart 代码编译产物与鸿蒙原生工程混合打包。

5.4 签名配置

开发调试阶段：可以使用 DevEco Studio 的自动签名功能：

用 DevEco Studio 打开 ohos/ 目录
File → Project Structure → Signing Configs
勾选 Automatically generate signature
登录华为开发者账号

发布阶段 ：需在 ohos/build-profile.json5 中配置正式证书：

json5 复制代码

{
  "signingConfigs": [
    {
      "name": "release",
      "material": {
        "certpath": "sign/release/entry-release.cer",
        "p12path": "sign/release/entry-release.p12",
        "profilepath": "sign/release/entry-release.p7b"
      }
    }
  ]
}

六、AS/DevEco Studio 配置

6.1 Android Studio 运行配置

新建运行配置项，在 Additional run args 中配置：

css 复制代码

--flavor=env_test --dart-define=ENVIRONMENT=test

6.2 DevEco Studio 运行

用 DevEco Studio 打开项目的 ohos/ 目录
选择目标设备（真机或模拟器）
点击运行按钮

如果遇到代码提示或跳转问题，可以尝试：

File → Invalidate Caches → 勾选 Clear file system cache
关闭 Power Save Mode

七、HAP 包生成

构建产物的默认路径为：

arduino 复制代码

build/ohos/haps/entry-default-signed.hap

这个 .hap 文件就是最终的安装包。

如果需要生成不同环境的包，可以通过 --flavor 参数指定：

bash 复制代码

flutter build hap --flavor=env_release --release

八、踩坑指南与最佳实践

8.1 版本兼容性

目前鸿蒙只适配到 Flutter 3.35.7 ，如果你的项目用了 3.44，需要降级。在 pubspec.yaml 中限制 SDK 版本：

yaml 复制代码

environment:
  sdk: '>=3.0.0 <3.10.0'
  flutter: ">=3.35.0 <3.36.0"

8.2 仓库地址变更

2026 年 6 月后，所有旧仓库（openharmony-tpc、openharmony-sig）将全面停止维护。请务必切换到 CPF-Flutter 新地址。

8.3 插件适配判断

如果某个插件在 CPF-Flutter 中找不到，先判断它是否真的需要适配------纯 Dart 库直接用就行，不需要任何修改。

8.4 环境管理建议

推荐使用 fvm 管理多个 Flutter 版本，实现官方版和鸿蒙版的无缝切换：

bash 复制代码

# 在项目根目录指定鸿蒙版 SDK
fvm use 3.35.7-ohos-1.0.0 --pin

8.5 性能优化亮点

Flutter-OH 3.35 在鸿蒙平台上做了深度性能优化：

预加载渲染管线：首帧延迟下降 37.8%
LTPO 动态帧率：负载降低约 20%
零脏区跳过渲染：消除不必要的 GPU 负载
DMA 内存后台释放：后台保活能力大幅增强

九、参考资料

结语

2026 年，Flutter 鸿蒙化已经从"能不能跑"进入"好不好用"的阶段。随着 CPF-Flutter 组织的成立和 124 个插件的集中迁移，开发者的接入成本大幅降低。希望这篇指南能帮你顺利完成 Flutter 项目的鸿蒙适配。如果过程中遇到问题，欢迎在评论区交流讨论。

本文基于 Flutter-OH 3.35.7 及 CPF-Flutter 2026 年 6 月生态状态编写，如有更新请以官方文档为准。