OpenHarmony工程：從環(huán)境搭建到HAP打包全攻略)
1. 先把核心鏈路說(shuō)清楚Flutter 是怎么跑到 OpenHarmony 上的如果你和我一樣第一次在 Flutter 工程里執(zhí)行flutter build hap時(shí)盯著屏幕等了幾分鐘最后拿到一個(gè).hap文件第一反應(yīng)多半是這個(gè)文件到底是怎么從那一堆 dart 和 ets 文件里變出來(lái)的我在把項(xiàng)目遷移到 OpenHarmony 平臺(tái)之前也以為只是“加一個(gè)構(gòu)建目標(biāo)”而已真正動(dòng)手才發(fā)現(xiàn)這背后的工程目錄結(jié)構(gòu)、構(gòu)建工具鏈和產(chǎn)物組織形式跟 Android/iOS 都有不少微妙的差異。這篇就是把我從環(huán)境搭建到編譯打包、再到踩坑排錯(cuò)的完整過程整理出來(lái)給準(zhǔn)備用 Flutter 編譯開發(fā) OpenHarmony 工程的同學(xué)做參考。先說(shuō)結(jié)論OpenHarmony 現(xiàn)在能跑 Flutter靠的不是原版 Flutter SDK而是 OpenHarmony SIG 維護(hù)的 flutter_flutter 分支。這個(gè)分支在 Flutter 官方工具鏈里加入了 ohos 這個(gè) target用來(lái)生成 OpenHarmony 工程骨架并支持把 Dart 代碼、Flutter engine 和原生插件一起打包成 HAPHarmonyOS Ability Package。換句話說(shuō)你寫的還是 Dart跑的還是 Flutter 那套自繪渲染引擎但宿主環(huán)境換成了 OpenHarmony 的 Ability 生命周期。1.1 一個(gè)容易誤解的事實(shí)原版 Flutter SDK 編譯不出 HAP很多人剛接觸時(shí)會(huì)問我已經(jīng)裝好 Flutter 了為什么flutter create出來(lái)的工程里沒有 ohos 目錄原因很簡(jiǎn)單原版 Flutter SDK 根本不認(rèn)識(shí) OpenHarmony 這個(gè)平臺(tái)。你需要在環(huán)境變量里把 flutter 指向 OpenHarmony SIG 發(fā)布的 flutter_flutter 分支然后執(zhí)行flutter doctor時(shí)才會(huì)出現(xiàn) ohos 相關(guān)的狀態(tài)項(xiàng)創(chuàng)建工程時(shí)也才能帶上--platforms ohos這樣的參數(shù)。這個(gè)分支本質(zhì)上是在 flutter_tools 層面加了 ohos 平臺(tái)支持包括工程模板、構(gòu)建命令、打包邏輯。所以版本對(duì)齊非常關(guān)鍵flutter_flutter 分支的版本要和你本地的 OpenHarmony SDK 版本配套。版本錯(cuò)配的時(shí)候最常見的表現(xiàn)就是創(chuàng)建工程能成功但構(gòu)建時(shí)報(bào)各種“找不到 Native API”或者“so 庫(kù)加載失敗”的錯(cuò)。我后面會(huì)在常見問題里專門展開。1.2 Flutter 與 OpenHarmony 的對(duì)接層從 Dart 到 ArkTS 的橋接思路運(yùn)行時(shí)鏈路是理解整個(gè)工程目錄的關(guān)鍵。OpenHarmony 上的 Flutter 應(yīng)用本質(zhì)上是一個(gè) OpenHarmony 應(yīng)用進(jìn)程里跑了一個(gè) Flutter engine。EntryAbility加載一個(gè) Flutter 容器頁(yè)Flutter engine 以動(dòng)態(tài)庫(kù)的形式打進(jìn) HAPDart 代碼通過 engine 執(zhí)行UI 由 Flutter 自繪引擎渲染不走 ArkUI 的組件樹。你在工程里寫的ets文件主要負(fù)責(zé) Ability 生命周期、系統(tǒng)能力接入和與 Dart 側(cè)的信令交互而真正業(yè)務(wù)界面基本都在lib目錄的 Dart 代碼里。這種模型帶來(lái)的直接影響是工程目錄會(huì)同時(shí)存在 Flutter 和 OpenHarmony 兩套原生骨架。你既要維護(hù)pubspec.yaml的依賴也要維護(hù)oh-package.json5和module.json5這些 OpenHarmony 側(cè)的配置。很多首次接觸的人就是被這個(gè)“雙軌制”搞暈的。2. 環(huán)境準(zhǔn)備版本對(duì)齊、工具鏈安裝、初始化一個(gè)可編譯的工程2.1 工具鏈清單與版本匹配關(guān)系我的建議是先把下面這幾樣?xùn)|西裝齊再談創(chuàng)建工程組件作用我當(dāng)前使用的版本區(qū)間flutter_flutterOpenHarmony 分支提供 ohos 平臺(tái)構(gòu)建能力跟隨 SIG 發(fā)布的最新 release 分支OpenHarmony SDK提供 ArkTS 編譯、SDK API、簽名工具5.0 系列對(duì)應(yīng) API 12DevEco StudioIDE主要用來(lái)管理 SDK、簽名和真機(jī)調(diào)試5.0 及以上ohpmOpenHarmony 包管理器安裝原生依賴隨 DevEco Studio 或獨(dú)立安裝hvigor構(gòu)建工具執(zhí)行 HAP 打包任務(wù)隨工程模板聲明版本Node.jshvigor 腳本運(yùn)行依賴建議 18 以上這里要特別強(qiáng)調(diào)版本匹配不是只看“最新”而是看 flutter_flutter 分支的說(shuō)明文檔里推薦的組合。官方 README 一般會(huì)寫清楚當(dāng)前分支適配 OpenHarmony 的哪個(gè) API Level。我自己就常年踩這個(gè)坑升級(jí) OpenHarmony SDK 后忘了同步升級(jí) flutter_flutter 分支結(jié)果構(gòu)建出的 HAP 在真機(jī)上啟動(dòng)后直接白屏。2.2 環(huán)境變量配置與首次 create 工程環(huán)境變量方面除了把 flutter 的 bin 目錄加進(jìn) PATH還需要確認(rèn) OpenHarmony SDK 的本地路徑能被構(gòu)建工具找到。我習(xí)慣在用戶環(huán)境變量里顯式聲明OHOS_SDK_HOME指向 DevEco Studio 內(nèi)置的 SDK 目錄如果你用命令行工具鏈建議把 ohpm 和 hvigor 的 bin 目錄也一起加進(jìn) PATH。配置完環(huán)境變量有個(gè)很常見的坑新開的終端才能生效已經(jīng)在跑的終端窗口里執(zhí)行flutter --version還是老版本。這不是你沒配置好而是 PATH 的生效機(jī)制就是如此。重開終端后可以用下面幾條命令快速驗(yàn)證flutter --version flutter doctor -v ohpm --versionflutter doctor -v輸出里如果能看到 ohos 相關(guān)項(xiàng)說(shuō)明分支切換成功如果沒看到大概率是 flutter SDK 路徑?jīng)]有切到 flutter_flutter 分支。接下來(lái)創(chuàng)建工程flutter create --platforms ohos --org com.example my_app cd my_app創(chuàng)建完成后查看工程根目錄你會(huì)發(fā)現(xiàn)多了一個(gè)ohos目錄這就是 OpenHarmony 原生工程的載體。如果創(chuàng)建時(shí)忘了加--platforms ohos可以回到根目錄補(bǔ)執(zhí)行flutter create --platforms ohos .但注意不要覆蓋已有代碼。驗(yàn)證工程能否跑起來(lái)最直接的方式是構(gòu)建一個(gè) debug 版 HAPflutter build hap --debug第一次構(gòu)建會(huì)拉取 Gradle 依賴、hvigor 依賴還有 Flutter engine 的預(yù)編譯產(chǎn)物時(shí)間比較長(zhǎng)是正常的。構(gòu)建成功后用 DevEco Studio 連接真機(jī)或模擬器安裝即可。2.3 從創(chuàng)建工程到跑起 Demo 的完整驗(yàn)證路徑我建議第一次別急著寫業(yè)務(wù)代碼先把默認(rèn)模板跑通。跑通的意義在于環(huán)境鏈路是通的后續(xù)出了問題可以排除“工具鏈沒裝對(duì)”這個(gè)因素專心查業(yè)務(wù)代碼。跑通 Demo 的步驟拆開來(lái)是flutter create --platforms ohos創(chuàng)建工程。flutter build hap --debug構(gòu)建出可安裝 HAP。DevEco Studio 打開工程配置簽名調(diào)試可以勾選自動(dòng)簽名。連接真機(jī)點(diǎn)擊運(yùn)行看到默認(rèn)計(jì)數(shù)器頁(yè)面就是成功。這一步如果失敗不要繼續(xù)往下寫業(yè)務(wù)代碼先回頭排查工具鏈版本。我在第 5 章列了一些高頻報(bào)錯(cuò)可以先對(duì)照看看。3. 工程目錄逐層拆解從根目錄到 ohos 子工程有哪些“暗樁”3.1 根目錄pubspec.yaml、.flutter-plugins-dependencies 與平臺(tái)目錄的對(duì)應(yīng)關(guān)系Flutter 工程根目錄的重要性不需要多講但在 OpenHarmony 適配場(chǎng)景下有幾個(gè)文件需要額外關(guān)注。pubspec.yaml除了聲明 Dart 依賴還決定了 Flutter 插件的加載范圍。當(dāng)你執(zhí)行flutter pub get后工程根目錄會(huì)生成.flutter-plugins-dependencies文件這個(gè) JSON 文件里記錄了所有啟用的插件及其各平臺(tái)實(shí)現(xiàn)路徑。點(diǎn)擊進(jìn)去能看到ohos字段它指向插件包里的 ohos 原生實(shí)現(xiàn)。如果你引入了一個(gè)第三方 Flutter 插件但發(fā)現(xiàn)構(gòu)建 HAP 時(shí)沒有把對(duì)應(yīng)的原生代碼編譯進(jìn)去十有八九是這個(gè)文件里沒有 ohos 實(shí)現(xiàn)信息——原因可能是插件本身沒提供 ohos 支持或者插件版本太舊。再看平臺(tái)目錄。標(biāo)準(zhǔn) Flutter 工程里android、ios目錄對(duì)應(yīng)各平臺(tái)的原生外殼在 OpenHarmony 適配分支下多出來(lái)的ohos目錄承擔(dān)了類似職責(zé)。三者并列存在互不干擾。但要注意.metadata這個(gè)隱藏文件里記錄了當(dāng)前工程的 Flutter 版本和生成工具版本如果你切了 flutter_flutter 的不同分支建議重新執(zhí)行一次flutter pub get必要時(shí)手動(dòng)檢查這個(gè)文件里的版本信息避免遺留舊數(shù)據(jù)。3.2 ohos 子工程HAP 的構(gòu)造骨架ohos目錄是整個(gè)工程里最值得花時(shí)間搞清楚的部分。它的結(jié)構(gòu)跟 DevEco Studio 創(chuàng)建的 OpenHarmony 工程基本一致ohos/ ├── AppScope/ │ ├── app.json5 │ └── resources/ ├── entry/ │ ├── build/ │ ├── libs/ │ ├── oh-package.json5 │ ├── build-profile.json5 │ ├── hvigorfile.ts │ └── src/main/ │ ├── module.json5 │ ├── ets/ │ ├── resources/ │ └── ... ├── build-profile.json5 ├── hvigorfile.ts ├── oh-package.json5 └── local.propertiesAppScope是應(yīng)用級(jí)配置app.json5里是應(yīng)用包名、版本號(hào)、icon 等全局信息。entry是默認(rèn)主模塊對(duì)應(yīng)一個(gè)可獨(dú)立運(yùn)行的 HAP。如果你后續(xù)要拆多個(gè)模塊可以在這個(gè)層級(jí)下繼續(xù)加模塊目錄。build-profile.json5分兩個(gè)層級(jí)外層工程級(jí)的負(fù)責(zé)配置簽名信息、模塊列表和 product 維度entry 內(nèi)層模塊級(jí)的負(fù)責(zé)當(dāng)前模塊的編譯配置。簽名文件通常在ohos/entry/build-profile.json5里通過signingConfigs引用DevEco Studio 的自動(dòng)簽名會(huì)幫你在~/.ohos/config/下維護(hù)個(gè)人信息文件不要手動(dòng)改這些 local 配置除非你知道自己在做什么。module.json5是最容易出問題的文件。它聲明了 Ability、權(quán)限和 extension 信息。比如要接入相機(jī)、圖庫(kù)、支付這類系統(tǒng)能力需要在這里加requestPermissions權(quán)限聲明。Flutter 插件機(jī)制在 OpenHarmony 側(cè)也是通過這個(gè)文件里的 extension 配置來(lái)注冊(cè)的插件開發(fā)者在文檔里一般會(huì)注明需要在module.json5中添加什么片段漏了這一段插件編譯能過但運(yùn)行時(shí)調(diào)用會(huì)直接失敗。3.3 lib 目錄組織與原生資源如何聯(lián)動(dòng)Dart 側(cè)的lib目錄組織決定了后續(xù)業(yè)務(wù)擴(kuò)展和原生橋接的復(fù)雜度。我自己的習(xí)慣是分成三層lib/pages/頁(yè)面級(jí)代碼只管 UI 和交互。lib/services/數(shù)據(jù)服務(wù)和平臺(tái)通道封裝比如本地?cái)?shù)據(jù)庫(kù)、后端同步、網(wǎng)絡(luò)請(qǐng)求。lib/platform/平臺(tái)通道的接口定義和實(shí)現(xiàn)分發(fā)邏輯。為什么要單獨(dú)拆platform層因?yàn)?OpenHarmony 適配意味著你想調(diào)用的某些系統(tǒng)能力圖庫(kù)、支付、推送沒有現(xiàn)成 pub 包需要自己寫 platform channel。把接口隔離在platform/目錄下Dart 側(cè)業(yè)務(wù)只依賴抽象接口實(shí)現(xiàn)分別在ohos/entry/src/main/ets/里用原生代碼完成。這樣后續(xù)切換平臺(tái)或者升級(jí)原生實(shí)現(xiàn)都不需要改業(yè)務(wù)頁(yè)面。原生資源走的是 OpenHarmony 的資源管理機(jī)制而不是 Flutter 的assets。比如你要在原生側(cè)顯示一個(gè)啟動(dòng)圖圖片放到entry/src/main/resources/base/media/下string 配置放到base/element/string.json。Flutter 側(cè)的圖片等資源依然放在工程根目錄的assets里通過pubspec.yaml聲明。兩套資源體系完全獨(dú)立記住這個(gè)規(guī)則找資源時(shí)就不會(huì)滿工程亂翻。3.4 Android/iOS 目錄與 ohos 目錄的異同做個(gè)對(duì)比方便有 Android 基礎(chǔ)的讀者快速遷移理解功能Android 目錄ohos 目錄應(yīng)用級(jí)配置android/app/build.gradleAppScope/app.json5build-profile.json5模塊清單AndroidManifest.xmlsrc/main/module.json5入口組件MainActivityEntryAbility原生代碼app/src/main/java/src/main/ets/資源文件app/src/main/res/src/main/resources/簽名文件keystorep12 / cer / p7b包管理器Gradleohpm hvigor結(jié)構(gòu)上可以說(shuō)高度對(duì)應(yīng)但在構(gòu)建鏈路細(xì)節(jié)上完全不同。Android 用 Gradle 構(gòu)建 APKOpenHarmony 用 hvigor 構(gòu)建 HAP。你在 Flutter 里執(zhí)行的flutter build hap實(shí)際上就是 flutter_tools 調(diào)用 hvigor 的封裝。理解這個(gè)關(guān)系后面看日志排錯(cuò)會(huì)快很多。4. 一次完整編譯產(chǎn)物在目錄間如何流轉(zhuǎn)并最終打成 HAP4.1 從 flutter build hap 到 HAP 落盤的關(guān)鍵流程命令行敲下flutter build hap --release之后構(gòu)建鏈路大致是這樣走的flutter pub get解析 Dart 依賴生成.flutter-plugins-dependencies。Dart 代碼編譯。release 模式走 AOT 編譯產(chǎn)出libapp.sodebug 模式產(chǎn)出kernel_blob.bin。Flutter engine 和插件原生代碼參與編譯。插件里ohos/目錄下的代碼會(huì)被 hvigor 編譯成對(duì)應(yīng)的.so庫(kù)。hvigor 讀取module.json5、build-profile.json5、資源和簽名配置把所有產(chǎn)物按 OpenHarmony 規(guī)范打包成 HAP。最終 HAP 落盤到build/ohos/或ohos/entry/build/下。從工程目錄的視角看這個(gè)流程里最關(guān)鍵的是第 2 步和第 3 步的產(chǎn)物去向。Flutter 的 AOT 編譯產(chǎn)物libapp.so會(huì)合并進(jìn) HAP 的libs/目錄插件編譯出的.so也會(huì)按架構(gòu)放在對(duì)應(yīng)目錄。如果你自定義了某個(gè)插件的原生實(shí)現(xiàn)改完代碼卻發(fā)現(xiàn) HAP 里沒有生效先檢查插件目錄下有沒有ohos子目錄、構(gòu)建產(chǎn)物有沒有更新。4.2 構(gòu)建產(chǎn)物目錄里到底有什么以我本地一個(gè)工程為例構(gòu)建完成后主要產(chǎn)物分布在這幾個(gè)地方build/ ├── flutter-build/ # Flutter 中間產(chǎn)物 │ ├── app.so # AOT 編譯產(chǎn)物 │ └── flutter_assets/ # Dart 側(cè)資源 ohos/entry/build/ ├── default/ │ ├── outputs/ # 最終的 HAP 包 │ ├── intermediate/ # hvigor 中間產(chǎn)物 │ └── ...拿到 HAP 后你可以用 DevEco Studio 自帶的工具或直接改后綴為 zip 打開看結(jié)構(gòu)。一個(gè)典型的 release HAP 里面會(huì)包含內(nèi)容說(shuō)明libs/arm64-v8a/各種.so包括 libflutter.so、libapp.so、插件 soets/編譯后的 ArkTS 字節(jié)碼resources/OpenHarmony 側(cè)資源module.json編譯后的模塊配置pack.info打包信息看到這個(gè)結(jié)構(gòu)你就明白為什么flutter build hap能一次搞定它把 Dart 運(yùn)行時(shí)、Flutter 引擎和 OpenHarmony 原生外殼全部融合到了一個(gè)包體里。4.3 調(diào)試模式與 release 模式的差異調(diào)試模式下Dart 代碼不會(huì)提前 AOT 編譯而是以kernel_blob.bin的形式打進(jìn) HAP配合flutter attach實(shí)現(xiàn)熱重載。因此 debug HAP 的體積比 release 大不少啟動(dòng)速度也會(huì)慢一些這是正常現(xiàn)象。有個(gè)細(xì)節(jié)值得注意OpenHarmony 上 Flutter 的熱重載前提是工程里的module.json5和插件注冊(cè)沒有被改壞。我遇到過一次熱重載失效排查了半天最后發(fā)現(xiàn)是module.json5里某個(gè)插件 extension 配置被 DevEco Studio 自動(dòng)格式化時(shí)調(diào)整了位置重新聲明后恢復(fù)正常。release 模式下則是完全 AOTFlutter 引擎執(zhí)行的是機(jī)器碼性能和啟動(dòng)速度都更接近原生應(yīng)用。日常開發(fā)用 debug發(fā)版一定用 release這個(gè)習(xí)慣在 OpenHarmony 工程里同樣適用。5. 編譯與運(yùn)行階段的高頻報(bào)錯(cuò)根因、排查鏈路與規(guī)避方案5.1 版本錯(cuò)配引發(fā)的“依賴下載不下來(lái)”與 Gradle 插件報(bào)錯(cuò)先說(shuō)我遇到最多的一類問題版本錯(cuò)配。具體表現(xiàn)有兩種。第一種ohpm install或flutter pub get時(shí)拉取依賴失敗報(bào)網(wǎng)絡(luò)或校驗(yàn)錯(cuò)誤。OpenHarmony 生態(tài)的包管理走的是 ohpm 倉(cāng)庫(kù)國(guó)內(nèi)網(wǎng)絡(luò)環(huán)境下偶爾會(huì)有倉(cāng)庫(kù)地址不通的問題。處理方式是在~/.ohpm/.ohpmrc里配置官方推薦的鏡像源然后清理本地緩存重新 install。第二種執(zhí)行構(gòu)建時(shí)報(bào) Gradle 相關(guān)的錯(cuò)誤。比如下面這類提示You are applying Flutters main Gradle plugin imperatively using the apply script這個(gè)報(bào)錯(cuò)一般不是 OpenHarmony 工程本身的問題而是 Flutter 分支版本和舊版 Android 緩存配置發(fā)生沖突的典型表現(xiàn)。升級(jí) Flutter 分支后老的android/settings.gradle或android/build.gradle里寫死了舊的插件應(yīng)用方式構(gòu)建時(shí)互相干擾。排查思路是檢查android/settings.gradle中的 plugin 配置是否和當(dāng)前 Flutter 版本匹配。如果不需要 Android 構(gòu)建直接把a(bǔ)ndroid目錄遷移或重生成一份。執(zhí)行flutter clean刪掉android/.gradle和build緩存重新構(gòu)建。由于我們只關(guān)心 OpenHarmony 目標(biāo)很多 Android 側(cè)的構(gòu)建兼容問題可以繞過不用死磕。5.2 接入鴻蒙原生能力時(shí)的配置問題以圖庫(kù)、IAP 為例用 Flutter 調(diào)用鴻蒙的圖庫(kù)是社區(qū)里問得非常多的問題。思路很明確走 platform channel。Dart 側(cè)用MethodChannel發(fā)消息原生側(cè)在EntryAbility或?qū)ｉT建的PhotoService.ets里接收消息調(diào)用 OpenHarmony 的 PhotoViewPicker API再把結(jié)果傳回 Dart。工程配置上有一處非常容易遺漏module.json5里必須聲明對(duì)應(yīng)的權(quán)限。{ module: { requestPermissions: [ { name: ohos.permission.READ_IMAGEVIDEO } ] } }漏掉權(quán)限清單編譯不會(huì)報(bào)錯(cuò)但點(diǎn)擊按鈕后頁(yè)面無(wú)響應(yīng)日志里會(huì)出現(xiàn)權(quán)限拒絕的信息。排查這類問題最有效的方式是把 DevEco Studio 的 HiLog 打開按進(jìn)程過濾直接搜Permission關(guān)鍵字。IAP 支付類似。OpenHarmony 側(cè)的支付 SDK 需要你在module.json5聲明對(duì)應(yīng)權(quán)限同時(shí)在oh-package.json5里引入支付 SDK 依賴。如果你只在 pub 層找了某個(gè)支付插件發(fā)現(xiàn)沒法拉起支付先檢查插件是否實(shí)現(xiàn)了 ohos 端再看 module 配置是否完整。很多支付插件只提供了 Android/iOS 實(shí)現(xiàn)在 OpenHarmony 上需要自己對(duì)接原生 SDK這種情況下插件的ohos目錄里應(yīng)該有原生適配代碼。這類問題的通用排查順序是確認(rèn)插件有沒有 ohos 實(shí)現(xiàn)。確認(rèn)module.json5權(quán)限和 extension 聲明完整。寫一個(gè)最簡(jiǎn)的測(cè)試頁(yè)面用一個(gè)固定 method 名調(diào)用原生邏輯驗(yàn)證通道通不通。用 HiLog 查看原生側(cè)異常。5.3 資源文件改動(dòng)不生效與熱重載失效的處理思路有同學(xué)在社區(qū)里反饋說(shuō)修改了資源文件里的 HTML 或配置構(gòu)建后界面沒變化懷疑是構(gòu)建緩存的問題。這個(gè)現(xiàn)象在 OpenHarmony 工程里我遇到過幾次大多數(shù)情況下確實(shí)和增量構(gòu)建緩存有關(guān)。處理方法是分層排查確認(rèn)改的是 Flutter 側(cè)資源還是 OpenHarmony 側(cè)資源。Flutter 側(cè)資源改動(dòng)后flutter clean再重新構(gòu)建即可OpenHarmony 側(cè)資源改動(dòng)后需要觸發(fā) hvigor 的重新編譯有時(shí)候要手動(dòng)刪掉ohos/entry/build下的緩存目錄。確認(rèn)資源文件命名是否符合規(guī)范資源名大小寫或非法字符可能導(dǎo)致編譯時(shí)資源被靜默忽略。如果界面沒變化但日志正常用 HAP 解包檢查 resources 里內(nèi)容是否更新。熱重載失效的另一個(gè)常見來(lái)源是module.json5被 DevEco Studio 和 flutter_tools 兩邊同時(shí)維護(hù)偶爾產(chǎn)生沖突。我的做法是原生側(cè)配置統(tǒng)一在 DevEco Studio 里改Dart 側(cè)統(tǒng)一在命令行或編輯器里改避免兩個(gè)工具交叉寫同一個(gè)文件的時(shí)間窗口。6. 我在目錄結(jié)構(gòu)維護(hù)上的一些長(zhǎng)期習(xí)慣6.1 目錄分層與多模塊管理的取舍OpenHarmony 工程的目錄結(jié)構(gòu)和 Android 類似支持多模塊。但我的建議是除非你的工程確實(shí)有獨(dú)立編譯、獨(dú)立升級(jí)的業(yè)務(wù)模塊否則不要一上來(lái)就拆多個(gè) module。多模塊帶來(lái)的構(gòu)建鏈路復(fù)雜度指數(shù)上升尤其是 Flutter 插件和 hvigor 的配置交互很容易出現(xiàn)“模塊 A 能編過模塊 B 編不過”的詭異狀態(tài)。我自己偏向用單模塊 目錄分包的方式組織原生代碼ohos/entry/src/main/ets/ ├── entryability/ ├── pages/ ├── service/ └── plugin/service放系統(tǒng)能力封裝plugin放 Flutter 插件對(duì)應(yīng)的原生實(shí)現(xiàn)。這樣既保持了職責(zé)清晰又不用承擔(dān)多模塊配置的額外成本。等業(yè)務(wù)規(guī)模真正到了需要獨(dú)立模塊的時(shí)候再按模塊拆也不遲。關(guān)于本地?cái)?shù)據(jù)庫(kù)和后端同步很多 Flutter 項(xiàng)目會(huì)用到 sqlite 或 drift 這類方案在 OpenHarmony 上要確認(rèn)插件是否支持 ohos 平臺(tái)。我目前的做法是把數(shù)據(jù)訪問層單獨(dú)放到lib/services/database/下用 sqflite 或 drift 的抽象接口如果某個(gè)插件沒有 ohos 實(shí)現(xiàn)就自己寫一個(gè)基于 OpenHarmony 關(guān)系型數(shù)據(jù)庫(kù)的適配層。目錄結(jié)構(gòu)的價(jià)值在這里就體現(xiàn)出來(lái)了適配層有明確的位置不會(huì)散落在各個(gè)頁(yè)面里。6.2 給新人的上手清單與個(gè)人體會(huì)最后整理一份快速清單給第一次用 Flutter 編譯開發(fā) OpenHarmony 工程的同學(xué)確認(rèn)用的是 OpenHarmony 適配版 Flutter SDK不是原版。確認(rèn) flutter_flutter 分支版本和 OpenHarmony SDK 版本匹配。flutter create --platforms ohos生成工程不要手動(dòng)拼目錄。先構(gòu)建默認(rèn) Demo 跑通再寫業(yè)務(wù)代碼。原生配置改完注意檢查module.json5權(quán)限和插件注冊(cè)都在這。構(gòu)建異常優(yōu)先f(wàn)lutter clean 刪緩存排除緩存干擾再查代碼。我自己踩過最深的坑其實(shí)就是版本管理。Flutter 的 OpenHarmony 適配分支更新頻率不算低團(tuán)隊(duì)協(xié)作時(shí)如果每個(gè)人拉的分支版本不一樣很容易出現(xiàn)“我這邊能編你那邊編不過”的情況。建議在工程根目錄用 git tag 或提交記錄把 flutter_flutter 分支的版本鎖定并在 README 里寫清楚當(dāng)前各工具鏈的版本組合。工程目錄結(jié)構(gòu)看著是靜態(tài)的靜態(tài)文件但它背后隱含的版本契約才是真正需要長(zhǎng)期維護(hù)的東西。把這個(gè)約定做扎實(shí)后面所有編譯問題都能少一半。 Flutter編譯開發(fā)OpenHarmony工程：從環(huán)境搭建到HAP打包全攻略
1. 先把核心鏈路說(shuō)清楚Flutter 是怎么跑到 OpenHarmony 上的如果你和我一樣第一次在 Flutter 工程里執(zhí)行flutter build hap時(shí)盯著屏幕等了幾分鐘最后拿到一個(gè).hap文件第一反應(yīng)多半是這個(gè)文件到底是怎么從那一堆 dart 和 ets 文件里變出來(lái)的我在把項(xiàng)目遷移到 OpenHarmony 平臺(tái)之前也以為只是“加一個(gè)構(gòu)建目標(biāo)”而已真正動(dòng)手才發(fā)現(xiàn)這背后的工程目錄結(jié)構(gòu)、構(gòu)建工具鏈和產(chǎn)物組織形式跟 Android/iOS 都有不少微妙的差異。這篇就是把我從環(huán)境搭建到編譯打包、再到踩坑排錯(cuò)的完整過程整理出來(lái)給準(zhǔn)備用 Flutter 編譯開發(fā) OpenHarmony 工程的同學(xué)做參考。先說(shuō)結(jié)論OpenHarmony 現(xiàn)在能跑 Flutter靠的不是原版 Flutter SDK而是 OpenHarmony SIG 維護(hù)的 flutter_flutter 分支。這個(gè)分支在 Flutter 官方工具鏈里加入了 ohos 這個(gè) target用來(lái)生成 OpenHarmony 工程骨架并支持把 Dart 代碼、Flutter engine 和原生插件一起打包成 HAPHarmonyOS Ability Package。換句話說(shuō)你寫的還是 Dart跑的還是 Flutter 那套自繪渲染引擎但宿主環(huán)境換成了 OpenHarmony 的 Ability 生命周期。1.1 一個(gè)容易誤解的事實(shí)原版 Flutter SDK 編譯不出 HAP很多人剛接觸時(shí)會(huì)問我已經(jīng)裝好 Flutter 了為什么flutter create出來(lái)的工程里沒有 ohos 目錄原因很簡(jiǎn)單原版 Flutter SDK 根本不認(rèn)識(shí) OpenHarmony 這個(gè)平臺(tái)。你需要在環(huán)境變量里把 flutter 指向 OpenHarmony SIG 發(fā)布的 flutter_flutter 分支然后執(zhí)行flutter doctor時(shí)才會(huì)出現(xiàn) ohos 相關(guān)的狀態(tài)項(xiàng)創(chuàng)建工程時(shí)也才能帶上--platforms ohos這樣的參數(shù)。這個(gè)分支本質(zhì)上是在 flutter_tools 層面加了 ohos 平臺(tái)支持包括工程模板、構(gòu)建命令、打包邏輯。所以版本對(duì)齊非常關(guān)鍵flutter_flutter 分支的版本要和你本地的 OpenHarmony SDK 版本配套。版本錯(cuò)配的時(shí)候最常見的表現(xiàn)就是創(chuàng)建工程能成功但構(gòu)建時(shí)報(bào)各種“找不到 Native API”或者“so 庫(kù)加載失敗”的錯(cuò)。我后面會(huì)在常見問題里專門展開。1.2 Flutter 與 OpenHarmony 的對(duì)接層從 Dart 到 ArkTS 的橋接思路運(yùn)行時(shí)鏈路是理解整個(gè)工程目錄的關(guān)鍵。OpenHarmony 上的 Flutter 應(yīng)用本質(zhì)上是一個(gè) OpenHarmony 應(yīng)用進(jìn)程里跑了一個(gè) Flutter engine。EntryAbility加載一個(gè) Flutter 容器頁(yè)Flutter engine 以動(dòng)態(tài)庫(kù)的形式打進(jìn) HAPDart 代碼通過 engine 執(zhí)行UI 由 Flutter 自繪引擎渲染不走 ArkUI 的組件樹。你在工程里寫的ets文件主要負(fù)責(zé) Ability 生命周期、系統(tǒng)能力接入和與 Dart 側(cè)的信令交互而真正業(yè)務(wù)界面基本都在lib目錄的 Dart 代碼里。這種模型帶來(lái)的直接影響是工程目錄會(huì)同時(shí)存在 Flutter 和 OpenHarmony 兩套原生骨架。你既要維護(hù)pubspec.yaml的依賴也要維護(hù)oh-package.json5和module.json5這些 OpenHarmony 側(cè)的配置。很多首次接觸的人就是被這個(gè)“雙軌制”搞暈的。2. 環(huán)境準(zhǔn)備版本對(duì)齊、工具鏈安裝、初始化一個(gè)可編譯的工程2.1 工具鏈清單與版本匹配關(guān)系我的建議是先把下面這幾樣?xùn)|西裝齊再談創(chuàng)建工程組件作用我當(dāng)前使用的版本區(qū)間flutter_flutterOpenHarmony 分支提供 ohos 平臺(tái)構(gòu)建能力跟隨 SIG 發(fā)布的最新 release 分支OpenHarmony SDK提供 ArkTS 編譯、SDK API、簽名工具5.0 系列對(duì)應(yīng) API 12DevEco StudioIDE主要用來(lái)管理 SDK、簽名和真機(jī)調(diào)試5.0 及以上ohpmOpenHarmony 包管理器安裝原生依賴隨 DevEco Studio 或獨(dú)立安裝hvigor構(gòu)建工具執(zhí)行 HAP 打包任務(wù)隨工程模板聲明版本Node.jshvigor 腳本運(yùn)行依賴建議 18 以上這里要特別強(qiáng)調(diào)版本匹配不是只看“最新”而是看 flutter_flutter 分支的說(shuō)明文檔里推薦的組合。官方 README 一般會(huì)寫清楚當(dāng)前分支適配 OpenHarmony 的哪個(gè) API Level。我自己就常年踩這個(gè)坑升級(jí) OpenHarmony SDK 后忘了同步升級(jí) flutter_flutter 分支結(jié)果構(gòu)建出的 HAP 在真機(jī)上啟動(dòng)后直接白屏。2.2 環(huán)境變量配置與首次 create 工程環(huán)境變量方面除了把 flutter 的 bin 目錄加進(jìn) PATH還需要確認(rèn) OpenHarmony SDK 的本地路徑能被構(gòu)建工具找到。我習(xí)慣在用戶環(huán)境變量里顯式聲明OHOS_SDK_HOME指向 DevEco Studio 內(nèi)置的 SDK 目錄如果你用命令行工具鏈建議把 ohpm 和 hvigor 的 bin 目錄也一起加進(jìn) PATH。配置完環(huán)境變量有個(gè)很常見的坑新開的終端才能生效已經(jīng)在跑的終端窗口里執(zhí)行flutter --version還是老版本。這不是你沒配置好而是 PATH 的生效機(jī)制就是如此。重開終端后可以用下面幾條命令快速驗(yàn)證flutter --version flutter doctor -v ohpm --versionflutter doctor -v輸出里如果能看到 ohos 相關(guān)項(xiàng)說(shuō)明分支切換成功如果沒看到大概率是 flutter SDK 路徑?jīng)]有切到 flutter_flutter 分支。接下來(lái)創(chuàng)建工程flutter create --platforms ohos --org com.example my_app cd my_app創(chuàng)建完成后查看工程根目錄你會(huì)發(fā)現(xiàn)多了一個(gè)ohos目錄這就是 OpenHarmony 原生工程的載體。如果創(chuàng)建時(shí)忘了加--platforms ohos可以回到根目錄補(bǔ)執(zhí)行flutter create --platforms ohos .但注意不要覆蓋已有代碼。驗(yàn)證工程能否跑起來(lái)最直接的方式是構(gòu)建一個(gè) debug 版 HAPflutter build hap --debug第一次構(gòu)建會(huì)拉取 Gradle 依賴、hvigor 依賴還有 Flutter engine 的預(yù)編譯產(chǎn)物時(shí)間比較長(zhǎng)是正常的。構(gòu)建成功后用 DevEco Studio 連接真機(jī)或模擬器安裝即可。2.3 從創(chuàng)建工程到跑起 Demo 的完整驗(yàn)證路徑我建議第一次別急著寫業(yè)務(wù)代碼先把默認(rèn)模板跑通。跑通的意義在于環(huán)境鏈路是通的后續(xù)出了問題可以排除“工具鏈沒裝對(duì)”這個(gè)因素專心查業(yè)務(wù)代碼。跑通 Demo 的步驟拆開來(lái)是flutter create --platforms ohos創(chuàng)建工程。flutter build hap --debug構(gòu)建出可安裝 HAP。DevEco Studio 打開工程配置簽名調(diào)試可以勾選自動(dòng)簽名。連接真機(jī)點(diǎn)擊運(yùn)行看到默認(rèn)計(jì)數(shù)器頁(yè)面就是成功。這一步如果失敗不要繼續(xù)往下寫業(yè)務(wù)代碼先回頭排查工具鏈版本。我在第 5 章列了一些高頻報(bào)錯(cuò)可以先對(duì)照看看。3. 工程目錄逐層拆解從根目錄到 ohos 子工程有哪些“暗樁”3.1 根目錄pubspec.yaml、.flutter-plugins-dependencies 與平臺(tái)目錄的對(duì)應(yīng)關(guān)系Flutter 工程根目錄的重要性不需要多講但在 OpenHarmony 適配場(chǎng)景下有幾個(gè)文件需要額外關(guān)注。pubspec.yaml除了聲明 Dart 依賴還決定了 Flutter 插件的加載范圍。當(dāng)你執(zhí)行flutter pub get后工程根目錄會(huì)生成.flutter-plugins-dependencies文件這個(gè) JSON 文件里記錄了所有啟用的插件及其各平臺(tái)實(shí)現(xiàn)路徑。點(diǎn)擊進(jìn)去能看到ohos字段它指向插件包里的 ohos 原生實(shí)現(xiàn)。如果你引入了一個(gè)第三方 Flutter 插件但發(fā)現(xiàn)構(gòu)建 HAP 時(shí)沒有把對(duì)應(yīng)的原生代碼編譯進(jìn)去十有八九是這個(gè)文件里沒有 ohos 實(shí)現(xiàn)信息——原因可能是插件本身沒提供 ohos 支持或者插件版本太舊。再看平臺(tái)目錄。標(biāo)準(zhǔn) Flutter 工程里android、ios目錄對(duì)應(yīng)各平臺(tái)的原生外殼在 OpenHarmony 適配分支下多出來(lái)的ohos目錄承擔(dān)了類似職責(zé)。三者并列存在互不干擾。但要注意.metadata這個(gè)隱藏文件里記錄了當(dāng)前工程的 Flutter 版本和生成工具版本如果你切了 flutter_flutter 的不同分支建議重新執(zhí)行一次flutter pub get必要時(shí)手動(dòng)檢查這個(gè)文件里的版本信息避免遺留舊數(shù)據(jù)。3.2 ohos 子工程HAP 的構(gòu)造骨架ohos目錄是整個(gè)工程里最值得花時(shí)間搞清楚的部分。它的結(jié)構(gòu)跟 DevEco Studio 創(chuàng)建的 OpenHarmony 工程基本一致ohos/ ├── AppScope/ │ ├── app.json5 │ └── resources/ ├── entry/ │ ├── build/ │ ├── libs/ │ ├── oh-package.json5 │ ├── build-profile.json5 │ ├── hvigorfile.ts │ └── src/main/ │ ├── module.json5 │ ├── ets/ │ ├── resources/ │ └── ... ├── build-profile.json5 ├── hvigorfile.ts ├── oh-package.json5 └── local.propertiesAppScope是應(yīng)用級(jí)配置app.json5里是應(yīng)用包名、版本號(hào)、icon 等全局信息。entry是默認(rèn)主模塊對(duì)應(yīng)一個(gè)可獨(dú)立運(yùn)行的 HAP。如果你后續(xù)要拆多個(gè)模塊可以在這個(gè)層級(jí)下繼續(xù)加模塊目錄。build-profile.json5分兩個(gè)層級(jí)外層工程級(jí)的負(fù)責(zé)配置簽名信息、模塊列表和 product 維度entry 內(nèi)層模塊級(jí)的負(fù)責(zé)當(dāng)前模塊的編譯配置。簽名文件通常在ohos/entry/build-profile.json5里通過signingConfigs引用DevEco Studio 的自動(dòng)簽名會(huì)幫你在~/.ohos/config/下維護(hù)個(gè)人信息文件不要手動(dòng)改這些 local 配置除非你知道自己在做什么。module.json5是最容易出問題的文件。它聲明了 Ability、權(quán)限和 extension 信息。比如要接入相機(jī)、圖庫(kù)、支付這類系統(tǒng)能力需要在這里加requestPermissions權(quán)限聲明。Flutter 插件機(jī)制在 OpenHarmony 側(cè)也是通過這個(gè)文件里的 extension 配置來(lái)注冊(cè)的插件開發(fā)者在文檔里一般會(huì)注明需要在module.json5中添加什么片段漏了這一段插件編譯能過但運(yùn)行時(shí)調(diào)用會(huì)直接失敗。3.3 lib 目錄組織與原生資源如何聯(lián)動(dòng)Dart 側(cè)的lib目錄組織決定了后續(xù)業(yè)務(wù)擴(kuò)展和原生橋接的復(fù)雜度。我自己的習(xí)慣是分成三層lib/pages/頁(yè)面級(jí)代碼只管 UI 和交互。lib/services/數(shù)據(jù)服務(wù)和平臺(tái)通道封裝比如本地?cái)?shù)據(jù)庫(kù)、后端同步、網(wǎng)絡(luò)請(qǐng)求。lib/platform/平臺(tái)通道的接口定義和實(shí)現(xiàn)分發(fā)邏輯。為什么要單獨(dú)拆platform層因?yàn)?OpenHarmony 適配意味著你想調(diào)用的某些系統(tǒng)能力圖庫(kù)、支付、推送沒有現(xiàn)成 pub 包需要自己寫 platform channel。把接口隔離在platform/目錄下Dart 側(cè)業(yè)務(wù)只依賴抽象接口實(shí)現(xiàn)分別在ohos/entry/src/main/ets/里用原生代碼完成。這樣后續(xù)切換平臺(tái)或者升級(jí)原生實(shí)現(xiàn)都不需要改業(yè)務(wù)頁(yè)面。原生資源走的是 OpenHarmony 的資源管理機(jī)制而不是 Flutter 的assets。比如你要在原生側(cè)顯示一個(gè)啟動(dòng)圖圖片放到entry/src/main/resources/base/media/下string 配置放到base/element/string.json。Flutter 側(cè)的圖片等資源依然放在工程根目錄的assets里通過pubspec.yaml聲明。兩套資源體系完全獨(dú)立記住這個(gè)規(guī)則找資源時(shí)就不會(huì)滿工程亂翻。3.4 Android/iOS 目錄與 ohos 目錄的異同做個(gè)對(duì)比方便有 Android 基礎(chǔ)的讀者快速遷移理解功能Android 目錄ohos 目錄應(yīng)用級(jí)配置android/app/build.gradleAppScope/app.json5build-profile.json5模塊清單AndroidManifest.xmlsrc/main/module.json5入口組件MainActivityEntryAbility原生代碼app/src/main/java/src/main/ets/資源文件app/src/main/res/src/main/resources/簽名文件keystorep12 / cer / p7b包管理器Gradleohpm hvigor結(jié)構(gòu)上可以說(shuō)高度對(duì)應(yīng)但在構(gòu)建鏈路細(xì)節(jié)上完全不同。Android 用 Gradle 構(gòu)建 APKOpenHarmony 用 hvigor 構(gòu)建 HAP。你在 Flutter 里執(zhí)行的flutter build hap實(shí)際上就是 flutter_tools 調(diào)用 hvigor 的封裝。理解這個(gè)關(guān)系后面看日志排錯(cuò)會(huì)快很多。4. 一次完整編譯產(chǎn)物在目錄間如何流轉(zhuǎn)并最終打成 HAP4.1 從 flutter build hap 到 HAP 落盤的關(guān)鍵流程命令行敲下flutter build hap --release之后構(gòu)建鏈路大致是這樣走的flutter pub get解析 Dart 依賴生成.flutter-plugins-dependencies。Dart 代碼編譯。release 模式走 AOT 編譯產(chǎn)出libapp.sodebug 模式產(chǎn)出kernel_blob.bin。Flutter engine 和插件原生代碼參與編譯。插件里ohos/目錄下的代碼會(huì)被 hvigor 編譯成對(duì)應(yīng)的.so庫(kù)。hvigor 讀取module.json5、build-profile.json5、資源和簽名配置把所有產(chǎn)物按 OpenHarmony 規(guī)范打包成 HAP。最終 HAP 落盤到build/ohos/或ohos/entry/build/下。從工程目錄的視角看這個(gè)流程里最關(guān)鍵的是第 2 步和第 3 步的產(chǎn)物去向。Flutter 的 AOT 編譯產(chǎn)物libapp.so會(huì)合并進(jìn) HAP 的libs/目錄插件編譯出的.so也會(huì)按架構(gòu)放在對(duì)應(yīng)目錄。如果你自定義了某個(gè)插件的原生實(shí)現(xiàn)改完代碼卻發(fā)現(xiàn) HAP 里沒有生效先檢查插件目錄下有沒有ohos子目錄、構(gòu)建產(chǎn)物有沒有更新。4.2 構(gòu)建產(chǎn)物目錄里到底有什么以我本地一個(gè)工程為例構(gòu)建完成后主要產(chǎn)物分布在這幾個(gè)地方build/ ├── flutter-build/ # Flutter 中間產(chǎn)物 │ ├── app.so # AOT 編譯產(chǎn)物 │ └── flutter_assets/ # Dart 側(cè)資源 ohos/entry/build/ ├── default/ │ ├── outputs/ # 最終的 HAP 包 │ ├── intermediate/ # hvigor 中間產(chǎn)物 │ └── ...拿到 HAP 后你可以用 DevEco Studio 自帶的工具或直接改后綴為 zip 打開看結(jié)構(gòu)。一個(gè)典型的 release HAP 里面會(huì)包含內(nèi)容說(shuō)明libs/arm64-v8a/各種.so包括 libflutter.so、libapp.so、插件 soets/編譯后的 ArkTS 字節(jié)碼resources/OpenHarmony 側(cè)資源module.json編譯后的模塊配置pack.info打包信息看到這個(gè)結(jié)構(gòu)你就明白為什么flutter build hap能一次搞定它把 Dart 運(yùn)行時(shí)、Flutter 引擎和 OpenHarmony 原生外殼全部融合到了一個(gè)包體里。4.3 調(diào)試模式與 release 模式的差異調(diào)試模式下Dart 代碼不會(huì)提前 AOT 編譯而是以kernel_blob.bin的形式打進(jìn) HAP配合flutter attach實(shí)現(xiàn)熱重載。因此 debug HAP 的體積比 release 大不少啟動(dòng)速度也會(huì)慢一些這是正常現(xiàn)象。有個(gè)細(xì)節(jié)值得注意OpenHarmony 上 Flutter 的熱重載前提是工程里的module.json5和插件注冊(cè)沒有被改壞。我遇到過一次熱重載失效排查了半天最后發(fā)現(xiàn)是module.json5里某個(gè)插件 extension 配置被 DevEco Studio 自動(dòng)格式化時(shí)調(diào)整了位置重新聲明后恢復(fù)正常。release 模式下則是完全 AOTFlutter 引擎執(zhí)行的是機(jī)器碼性能和啟動(dòng)速度都更接近原生應(yīng)用。日常開發(fā)用 debug發(fā)版一定用 release這個(gè)習(xí)慣在 OpenHarmony 工程里同樣適用。5. 編譯與運(yùn)行階段的高頻報(bào)錯(cuò)根因、排查鏈路與規(guī)避方案5.1 版本錯(cuò)配引發(fā)的“依賴下載不下來(lái)”與 Gradle 插件報(bào)錯(cuò)先說(shuō)我遇到最多的一類問題版本錯(cuò)配。具體表現(xiàn)有兩種。第一種ohpm install或flutter pub get時(shí)拉取依賴失敗報(bào)網(wǎng)絡(luò)或校驗(yàn)錯(cuò)誤。OpenHarmony 生態(tài)的包管理走的是 ohpm 倉(cāng)庫(kù)國(guó)內(nèi)網(wǎng)絡(luò)環(huán)境下偶爾會(huì)有倉(cāng)庫(kù)地址不通的問題。處理方式是在~/.ohpm/.ohpmrc里配置官方推薦的鏡像源然后清理本地緩存重新 install。第二種執(zhí)行構(gòu)建時(shí)報(bào) Gradle 相關(guān)的錯(cuò)誤。比如下面這類提示You are applying Flutters main Gradle plugin imperatively using the apply script這個(gè)報(bào)錯(cuò)一般不是 OpenHarmony 工程本身的問題而是 Flutter 分支版本和舊版 Android 緩存配置發(fā)生沖突的典型表現(xiàn)。升級(jí) Flutter 分支后老的android/settings.gradle或android/build.gradle里寫死了舊的插件應(yīng)用方式構(gòu)建時(shí)互相干擾。排查思路是檢查android/settings.gradle中的 plugin 配置是否和當(dāng)前 Flutter 版本匹配。如果不需要 Android 構(gòu)建直接把a(bǔ)ndroid目錄遷移或重生成一份。執(zhí)行flutter clean刪掉android/.gradle和build緩存重新構(gòu)建。由于我們只關(guān)心 OpenHarmony 目標(biāo)很多 Android 側(cè)的構(gòu)建兼容問題可以繞過不用死磕。5.2 接入鴻蒙原生能力時(shí)的配置問題以圖庫(kù)、IAP 為例用 Flutter 調(diào)用鴻蒙的圖庫(kù)是社區(qū)里問得非常多的問題。思路很明確走 platform channel。Dart 側(cè)用MethodChannel發(fā)消息原生側(cè)在EntryAbility或?qū)ｉT建的PhotoService.ets里接收消息調(diào)用 OpenHarmony 的 PhotoViewPicker API再把結(jié)果傳回 Dart。工程配置上有一處非常容易遺漏module.json5里必須聲明對(duì)應(yīng)的權(quán)限。{ module: { requestPermissions: [ { name: ohos.permission.READ_IMAGEVIDEO } ] } }漏掉權(quán)限清單編譯不會(huì)報(bào)錯(cuò)但點(diǎn)擊按鈕后頁(yè)面無(wú)響應(yīng)日志里會(huì)出現(xiàn)權(quán)限拒絕的信息。排查這類問題最有效的方式是把 DevEco Studio 的 HiLog 打開按進(jìn)程過濾直接搜Permission關(guān)鍵字。IAP 支付類似。OpenHarmony 側(cè)的支付 SDK 需要你在module.json5聲明對(duì)應(yīng)權(quán)限同時(shí)在oh-package.json5里引入支付 SDK 依賴。如果你只在 pub 層找了某個(gè)支付插件發(fā)現(xiàn)沒法拉起支付先檢查插件是否實(shí)現(xiàn)了 ohos 端再看 module 配置是否完整。很多支付插件只提供了 Android/iOS 實(shí)現(xiàn)在 OpenHarmony 上需要自己對(duì)接原生 SDK這種情況下插件的ohos目錄里應(yīng)該有原生適配代碼。這類問題的通用排查順序是確認(rèn)插件有沒有 ohos 實(shí)現(xiàn)。確認(rèn)module.json5權(quán)限和 extension 聲明完整。寫一個(gè)最簡(jiǎn)的測(cè)試頁(yè)面用一個(gè)固定 method 名調(diào)用原生邏輯驗(yàn)證通道通不通。用 HiLog 查看原生側(cè)異常。5.3 資源文件改動(dòng)不生效與熱重載失效的處理思路有同學(xué)在社區(qū)里反饋說(shuō)修改了資源文件里的 HTML 或配置構(gòu)建后界面沒變化懷疑是構(gòu)建緩存的問題。這個(gè)現(xiàn)象在 OpenHarmony 工程里我遇到過幾次大多數(shù)情況下確實(shí)和增量構(gòu)建緩存有關(guān)。處理方法是分層排查確認(rèn)改的是 Flutter 側(cè)資源還是 OpenHarmony 側(cè)資源。Flutter 側(cè)資源改動(dòng)后flutter clean再重新構(gòu)建即可OpenHarmony 側(cè)資源改動(dòng)后需要觸發(fā) hvigor 的重新編譯有時(shí)候要手動(dòng)刪掉ohos/entry/build下的緩存目錄。確認(rèn)資源文件命名是否符合規(guī)范資源名大小寫或非法字符可能導(dǎo)致編譯時(shí)資源被靜默忽略。如果界面沒變化但日志正常用 HAP 解包檢查 resources 里內(nèi)容是否更新。熱重載失效的另一個(gè)常見來(lái)源是module.json5被 DevEco Studio 和 flutter_tools 兩邊同時(shí)維護(hù)偶爾產(chǎn)生沖突。我的做法是原生側(cè)配置統(tǒng)一在 DevEco Studio 里改Dart 側(cè)統(tǒng)一在命令行或編輯器里改避免兩個(gè)工具交叉寫同一個(gè)文件的時(shí)間窗口。6. 我在目錄結(jié)構(gòu)維護(hù)上的一些長(zhǎng)期習(xí)慣6.1 目錄分層與多模塊管理的取舍OpenHarmony 工程的目錄結(jié)構(gòu)和 Android 類似支持多模塊。但我的建議是除非你的工程確實(shí)有獨(dú)立編譯、獨(dú)立升級(jí)的業(yè)務(wù)模塊否則不要一上來(lái)就拆多個(gè) module。多模塊帶來(lái)的構(gòu)建鏈路復(fù)雜度指數(shù)上升尤其是 Flutter 插件和 hvigor 的配置交互很容易出現(xiàn)“模塊 A 能編過模塊 B 編不過”的詭異狀態(tài)。我自己偏向用單模塊 目錄分包的方式組織原生代碼ohos/entry/src/main/ets/ ├── entryability/ ├── pages/ ├── service/ └── plugin/service放系統(tǒng)能力封裝plugin放 Flutter 插件對(duì)應(yīng)的原生實(shí)現(xiàn)。這樣既保持了職責(zé)清晰又不用承擔(dān)多模塊配置的額外成本。等業(yè)務(wù)規(guī)模真正到了需要獨(dú)立模塊的時(shí)候再按模塊拆也不遲。關(guān)于本地?cái)?shù)據(jù)庫(kù)和后端同步很多 Flutter 項(xiàng)目會(huì)用到 sqlite 或 drift 這類方案在 OpenHarmony 上要確認(rèn)插件是否支持 ohos 平臺(tái)。我目前的做法是把數(shù)據(jù)訪問層單獨(dú)放到lib/services/database/下用 sqflite 或 drift 的抽象接口如果某個(gè)插件沒有 ohos 實(shí)現(xiàn)就自己寫一個(gè)基于 OpenHarmony 關(guān)系型數(shù)據(jù)庫(kù)的適配層。目錄結(jié)構(gòu)的價(jià)值在這里就體現(xiàn)出來(lái)了適配層有明確的位置不會(huì)散落在各個(gè)頁(yè)面里。6.2 給新人的上手清單與個(gè)人體會(huì)最后整理一份快速清單給第一次用 Flutter 編譯開發(fā) OpenHarmony 工程的同學(xué)確認(rèn)用的是 OpenHarmony 適配版 Flutter SDK不是原版。確認(rèn) flutter_flutter 分支版本和 OpenHarmony SDK 版本匹配。flutter create --platforms ohos生成工程不要手動(dòng)拼目錄。先構(gòu)建默認(rèn) Demo 跑通再寫業(yè)務(wù)代碼。原生配置改完注意檢查module.json5權(quán)限和插件注冊(cè)都在這。構(gòu)建異常優(yōu)先f(wàn)lutter clean 刪緩存排除緩存干擾再查代碼。我自己踩過最深的坑其實(shí)就是版本管理。Flutter 的 OpenHarmony 適配分支更新頻率不算低團(tuán)隊(duì)協(xié)作時(shí)如果每個(gè)人拉的分支版本不一樣很容易出現(xiàn)“我這邊能編你那邊編不過”的情況。建議在工程根目錄用 git tag 或提交記錄把 flutter_flutter 分支的版本鎖定并在 README 里寫清楚當(dāng)前各工具鏈的版本組合。工程目錄結(jié)構(gòu)看著是靜態(tài)的靜態(tài)文件但它背后隱含的版本契約才是真正需要長(zhǎng)期維護(hù)的東西。把這個(gè)約定做扎實(shí)后面所有編譯問題都能少一半。