本文原創發佈在華為開發者聯盟社區，歡迎前往與更多開發者進行互動。
更多相關問題可點擊原帖進行交流：Flutter應用如何快速適配HarmonyOS 。
概述
當前已有適配了HarmonyOS的ohos Flutter SDK，當前已有眾多Flutter應用基於此版本上架鴻蒙應用市場。
目前可使用的有3.7.12、3.22及3.27三個版本，3.32也已經在Beta中。
本文旨在介紹如何將Flutter應用快速適配HarmonyOS，包含以下幾個方面：
- 整體方案
- 版本選擇
- 技術架構選型
- 工作量評估
- 環境準備
- 命令行工具
- 如何調試
- 三方庫替換
- 應用權限申請
- 打包和發佈
整體方案
- 先選擇確認要使用的HarmonyOS Flutter SDK的版本，然後下載配置好開發環境，在進行HarmonyOS Flutter應用開發時記得切換SDK，可以使用flutter doctor -v進行檢查
-
確認架構選型，是使用Flutter App還是採用Flutter module混合開發，一般延用Android/IOS上的選型
- flutter app方式：可以在原先項目根目錄執行命令
flutter create --platforms ohos --t app ./，會自動創建HarmonyOS底座工程目錄ohos，與ios和android目錄並列 - flutter module方式：參考在HarmonyOS上集成Flutter module，最終會將module打包成har包，供HarmonyOS工程引用，類比於Flutter module在Android上會被構建成AAR包，供APK集成。
- flutter app方式：可以在原先項目根目錄執行命令
- 三方庫替換成鴻蒙化的版本，需採用Git依賴的方式
- 未適配的三方庫一般替換成同類功能的庫
- 自研的插件需要自行適配，可以在原先插件工程的根目錄下執行命令
flutter create --platforms ohos --t plugin ./，也會自動創建插件鴻蒙平台代碼目錄ohos，與android和ios並列 - 平台代碼重寫，例如原來在Android平台上開發的Java代碼，適配時需要重寫成ArkTS代碼
-
打包驗證，目前也有兩種方案：
- 一套代碼，一套流水線：鴻蒙版Flutter SDK也可以編譯打包支持Android/IOS平台運行的包（APK或ipa），使用方便，與普通版本完全一致
- 一套代碼，兩套流水線：HarmonyOS和Android/ios分別採用不同的Flutter SDK編譯構建，最大程度複用代碼
- 測試與發佈
版本選擇
之前在Android/IOS上使用的Flutter版本可能與適配HarmonyOS的Flutter版本不同，這需要做版本的升級，當前有三個版本適配了HarmonyOS，分別對應社區Flutter SDK的：3.7.12、3.22.0和3.27.4
切換建議：
- 升級前做好備份
- 選擇與當前版本差異最小的版本，逐步升級
- 做好測試用例保護
Flutter版本升級
存量項目或歷史版本需先調整至上述支持版本，按 “最小適配成本” 選擇，由於小版本升級不會有破壞性改動，所以僅關注版本號前兩位即可：
- 當前版本 < 3.7 → 升級至 3.7.12
- 3.7 < 當前版本 < 3.22 → 升級至 3.22.0
- 3.22 < 當前版本 < 3.27 → 升級至 3.27.4
- 當前版本 > 3.27 → 降級至 3.27.4
在升級Flutter時遇到的Dart錯誤，可以使用dart fix命令自動修復代碼，大多數破壞性改動是支持自動修復的，具體可以參考Flutter官方提供的升級指導：
- 3.7破壞性改動
- 3.22破壞性改動
- 3.27破壞性改動
注意當升級跨多個版本時，需要關注這中間多個版本的破壞性改動
技術架構選型
Flutter開發App有2種模式：純Flutter APP和混合開發。
純Flutter APP和混合開發對比：
| 維度 | 純 Flutter APP | 混合開發 |
|---|---|---|
| 開發範圍 | 全棧 Flutter，HarmonyOS僅作容器 | 部分Flutter + 主HarmonyOS工程 |
| 原生功能適配 | 較難（需通過通道調用） | 便捷（原生模塊直接調用） |
| 開發 / 維護成本 | 低（單一技術棧） | 高（多技術棧協作） |
選型策略：
- 全新項目，無存量代碼：推薦選純Flutter APP模式，從零開始用Flutter可最大化發揮 “一套代碼跨多端” 的優勢，避免混合開發的集成成本，迭代效率更高。
- 已有成熟原生APP，新功能使用Flutter開發：僅需適配現有安卓ios代碼為HarmonOS代碼，原生開發更便捷，新業務需求集成Flutter代碼，實現跨端開發。
- 需深度利用平台特性：推薦使用混合開發，複雜原生功能通過原生代碼實現更穩定，Flutter僅負責上層UI，避免通過Platform Channel頻繁通信導致的性能損耗和調試複雜度。
工作量評估
適配過程中，工作量主要有以下幾部分組成：
-
三方庫替換
- Flutter Plugin中會涉及到平台代碼，當適配HarmonyOS時，也需要對這些plugin也進行鴻蒙化。根據使用量排序已經適配了一批plugin，歸檔在GitCode上，使用方法可以參考Flutter三方庫依賴引用及常見問題
- 針對尚未適配的插件可以去官方開發者論壇提需求，會有官方技術支持響應評估，可以選擇功能相同或類似的鴻蒙化插件進行替換
- 針對自研插件，需要自行適配，文檔可以參考開發plugin
- 平台代碼適配
Android或者IOS上可能開發了一些平台代碼（Java、swift等），在適配時，需要將此部分代碼使用ArkTS重寫，經驗評估： ArkTS代碼行數 = 0.7 * Java代碼行數 -
C++相關適配
分為SO和源碼兩種：- SO文件需要對源碼進行交叉編譯成HarmonyOS上可運行的SO，再使用
dart:ffi調用 - 源碼可以使用FFI插件的方式，HarmonyOS上需要使用cmake進行編譯
- SO文件需要對源碼進行交叉編譯成HarmonyOS上可運行的SO，再使用
可以結合自身對相關技術的掌握程度評估具體工作量
環境準備
- 先安裝好最新release版本的DevEco Studio
- 下載鴻蒙版本的Flutter SDK
- 由於當前DevEco Studio不支持Dart開發，還需要額外下載VSCode或者Android Studio進行Dart開發和調試
- 以上完成後配置環境變量
以上完成後就可以開發HarmonyOS上的Flutter應用了
命令行工具
Flutter命令行工具也做了鴻蒙化，使用起來和在Android上十分類似，環境配置完後即可使用，可以直接通過命令創建Flutter鴻蒙模板工程，打包成har、hap或者app包，或者運行程序等等。列舉了一些常用的命令如下：
| 指令名稱 | 指令描述 | 使用説明 |
|---|---|---|
| doctor | 環境檢測 | flutter doctor -v |
| create | 創建新項目 | flutter create --platforms ohos,android,ios --org \<org\> \<appName\> |
| create | 創建module模板 | flutter create -t module \<module_name\> |
| create | 創建plugin模板 | flutter create -t plugin --platforms ohos,android,ios \<plugin_name\> |
| create | 創建plugin_ffi模板 | flutter create -t plugin_ffi --platforms ohos,android,ios \<plugin_name\> |
| devices | 已連接設備查找 | flutter devices |
| build | 測試應用構建 | flutter build hap --debug [--target-platform ohos-arm64] |
| build | 正式應用構建 | flutter build hap --release [--target-platform ohos-arm64] |
| run | 應用運行 | flutter run |
| attach | 調試模式 | flutter attach |
| pub | 獲取依賴 | flutter pub get |
| clean | 清除項目依賴 | flutter clean |
| cache | 清除全局緩存數據 | flutter pub cache clean |
參考完整命令列表
如何調試
由於當前DevEco Studio無法調試Dart代碼，因此日常開發調試需使用2個IDE：Deveco Studio+Android Studio或VSCode。
-
Flutter App類型：
-
如何調試ArkTS代碼
- 連接真機或模擬器,真機需啓用開發者選項，並打開USB調試，使用Deveco Studio打開ohos目錄，並配置調試簽名。
- 在Flutter工程根目錄下執行flutter build hap構建出hap包。
- 在需要調試的Arkts代碼行打上斷點，點擊第一步中DevEco Studio的右上角debug按鈕運行應用程序，即可調試ArkTS代碼。
-
如何調試Dart代碼
- 使用Android Studio打開工程，找到main.dart文件，debug運行main方法。
- 使用VSCode打開工程，找到main.dart文件，debug運行main方法。
-
-
混合開發類型：
- 參考app類型如何調試ArkTS代碼, debug運行ohos工程。
- 調試Dart碼時，使用android studio或vscode，通過flutter attach連接已經運行的應用程序，此時可以斷點調試Dart，也可熱重載Dart代碼。
三方庫替換
- 純Dart庫
可以直接引用pub上的版本，不涉及HarmonyOS適配工作 - 已適配HarmonyOS三方庫
需要採用git方式進行引用，詳細可以參考Flutter三方庫依賴引用及常見問題 - 插件未適配
可以去官方開發者論壇提需求，會有官方技術支持響應評估，可以選擇功能相同或類似的鴻蒙化插件進行替換 - 自定義三方插件
需要自行適配，文檔可以參考開發plugin
申請應用權限
- 應用使用權限配置
應用在申請權限時，需在項目的配置文件module.json5中逐個聲明權限。
用户權限申請需使用Permission_Handler插件。 -
受限權限申請
受限開放的權限通常是不允許三方應用申請的：- 需要評估當前應用場景是否可申請受限權限,如滿足申請條件，可提供相關申請材料到應用市場申請相應權限
- 通常在三方插件中如Wechat_Asset_Picker等涉及受限權限，可考慮使用其它三方庫替換，例如image_picker
- 另外有些受限權限，文檔建議使用安全控件替代，但是跨端框架無法使用安全控件，申請的時候可以註明此應用是跨端框架開發的應用，一般可以通過申請
打包和發佈
-
測試/生產證書管理、環境隔離
- 自動簽名：開發自測階段，IDE提供了自動簽名方式快速簽名，且開放了ACL權限，以及開通開放能力（推送、地圖等），方便開發者快速開發調試。
- 手動簽名：發佈上架應用階段，需使用手動簽名方式申請發佈證書，需手動在AGC平台上申請ACL權限且審批通過，需開通開放能力。
-
構建release包
-
使用Deveco Studio構建App包：
- 在Flutter工程中執行命令行flutter build har --release構建har包。
- 參考打包APP使用Deveco Studio工具構建App包,打包產物路徑ohos/build/outputs/default/*.app。
- 使用Flutter構建App包(純Flutter應用)：
使用發佈證書替換調試證書後，執行命令行flutter build app --release即可編譯構建出app包，打包產物路徑：ohos/build/outputs/default/*.app。 -
混合開發應用：
- har包引入：Flutter module編譯release的har包，替換Ohos工程中的har包，使用Deveco Studio構建App包。
- 源碼引入：直接使用Deveco Studio構建App包。
-
-
發佈AppGallery Connect
- 發佈HarmonyOS應用:應用正式發佈到華為應用市場前,AGC審核人員會進行會審核開發者提交的所有信息。
- 邀請測試:正式版本發佈之前，您可以選擇特定用户羣組來測試您的應用，以收集測試用户的反饋意見，助您提前發現問題，及時修復和優化版本體驗
- 內部測試:可以將應用發佈上傳至您的服務器或者第三方雲上，團隊參與測試的人員可以將應用下載到授權的設備上測試。
- 蒲公英測試：蒲公英平台提供了分發HarmonyOS應用的服務，IOS開發者能夠快速的掌握分發測試HarmonyOS應用。
