背景与概述

• OpenHarmony版Flutter文档资料涵盖了架构介绍、版本计划、环境搭建、功能开发、应用质量、三方库接入、场景化案例、常见问题等主题，帮助开发者完成开发。
• Flutter 3.16+ 

环境配置指令

• 安装Flutter SDK并配置环境变量
• 具体可以参考我的另外一篇文章：
• 【2025最新】Flutter开发OpenHarmony应用全指南-CSDN博客
• 以及逸轩大佬的：
• 【2025最新】Flutter 编译开发 鸿蒙HarmonyOS 6 项目教程（Windows）_flutter 鸿蒙-CSDN博客
   
• 检查一下环境

• flutter doctor -v

  安装鸿蒙适配依赖

• 输入指令，给Flutter装个“开源鸿蒙小插件”，确保编译时不出错：

• 安装开源鸿蒙适配插件（开源社区主流插件）：

• flutter pub add flutter_openharmony
  

  把Flutter升级到最新稳定版（避免版本兼容问题）：

• flutter upgrade

  至于构建项目，别的文章里写的很详细了。

生成开源鸿蒙安装包

开发完要生成安装包，开源鸿蒙支持两种格式：APK（兼容格式）和HAP（原生格式，上架应用市场用）。

编译APK包（简单通用）

编译debug版APK（测试用，有调试信息）

flutter build openharmony --debug

编译release版APK（正式用，体积小、速度快）

flutter build openharmony --release

指定输出路径（默认在build目录，改路径方便查找）

flutter build openharmony --release --output-dir ./my_apk

编译HAP包（开源鸿蒙原生格式）

要上架开源鸿蒙应用市场必须用HAP包，需要DevEco Studio配合，分两步：

第一步：用Flutter编译中间文件（项目目录下执行）

flutter build openharmony --release

第二步：用DevEco Studio打包HAP（终端进入harmony模块目录）

cd my_openharmony_app/harmony
hdc build --mode release --ohos-version 10

小技巧：如果嫌终端麻烦，第二步可以直接在DevEco Studio里点“Build HAP(s)”按钮，图形化操作更简单。

打包发布：上架鸿蒙应用市场

生成签名证书（仅做1次）

核心指令：生成签名证书（复制完整指令，别换行）

keytool -genkey -v -keystore my_openharmony_key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias ohos_key

1. 输入指令后，按提示输“密钥库密码”（自己记牢，比如123456）

2. 接着输姓名、组织等信息（随便填，不影响上架）

3. 最后输“密钥密码”（建议和密钥库密码一样，方便记）

生成后，证书文件“my_openharmony_key.jks”会在当前目录，把它复制到项目的“harmony”文件夹下。

配置签名并生成发布包

在项目的“harmony”目录下新建“sign_config.json”文件，粘贴以下内容（改里面的密码和路径）：

{
  "signKeyAlias": "ohos_key",
  "signKeyPassword": "你的密钥密码",
  "signStorePassword": "你的密钥库密码",
  "signStorePath": "my_openharmony_key.jks"
}

然后执行打包指令：

进入openharmony模块目录

cd my_openharmony_app/harmony

生成带签名的HAP发布包

hdc build --mode release --ohos-version 10 --sign-config sign_config.json

依赖管理：给项目加功能插件

开发时要加地图、支付等功能，就得装依赖插件，指令都在项目目录下执行：

# 1. 安装依赖（比如装开源鸿蒙地图插件）
flutter pub add ohos_map_plugin

# 2. 安装指定版本（避免新版本有bug）
flutter pub add ohos_map_plugin:1.0.0

# 3. 更新所有依赖到最新版
flutter pub upgrade

# 4. 删除不需要的依赖
flutter pub remove ohos_map_plugin

# 5. 检查依赖是否兼容开源鸿蒙
flutter pub audit --platform openharmony

避坑提示：装依赖后如果报错，先执行“flutter pub get”刷新依赖，还不行就看插件官网的适配说明。

问题排查：小白常见报错解决

编译报错：缓存问题

症状：明明改了配置却还是报错，或提示“build failed”

# 清理Flutter缓存
flutter clean

# 清理开源鸿蒙SDK缓存
hdc clean cache

# 重新构建项目
flutter pub get
flutter run

其它常见指令

指令	作用	适用场景
flutter doctor	检查环境问题	刚装完环境或报错时
flutter create --platforms openharmony 项目名	新建开源鸿蒙项目	开发初期
flutter run -r	热重载运行	写代码时实时预览
flutter build openharmony --release	编译release版APK	本地测试安装
hdc build --mode release	编译HAP发布包	上架应用市场
flutter clean	清理缓存	编译报错时
flutter logs -d 设备ID	查看应用日志	找报错原因

小白必看注意事项

• 版本匹配：Flutter用3.16+，开源鸿蒙SDK用API10+，版本太低会有兼容问题

• 路径别含中文：项目目录和SDK路径都别放中文，比如“D:\开发项目”会报错，改成“D:\dev_project”

• 模拟器启动慢：第一次启动要等几分钟，耐心等，别反复点启动

• 签名文件备份：生成的.jks证书文件一定要备份，上架后更新应用还要用

• 查官方文档：遇到特殊问题，去“开源鸿蒙官网”或“Flutter中文网”找最新说明

按上面的指令和说明一步步操作，小白也能顺利完成Flutter开源鸿蒙应用的开发和上架。如果某条指令报错，先看“问题排查”模块，大部分问题都能解决~