Flutter在OpenHarmony生态里跑起来这件事前一阵子折腾了不少时间。这篇是系列第二篇重点解决两个问题一个是代码仓库怎么用AtomGit搭起来另一个是OpenHarmony应用做热更新的几种常见打法。最后会带一个能直接跑的示例把配置和更新串起来看效果。适合正打算在OpenHarmony上做Flutter适配、又被仓库和更新流程卡住的开发者参考。先说下我手上这套环境设备端是OpenHarmony 4.0 Release开发框架用的是DevEco StudioFlutter SDK用的是OpenHarmony官方适配的分支版本。这个组合目前算比较稳的后面所有操作都基于这套环境。如果你还是3.2或者更早的版本建议先升级不然后面有些配置项和API对不上。1. 项目前置逻辑为什么先搞定仓库和热更新在OpenHarmony上做Flutter开发跟安卓/iOS最大的不同在于你既要管Flutter侧的Dart代码又要管OpenHarmony侧的元服务打包逻辑。很多团队第一步就卡在代码托管上——OpenHarmony生态下常用的Git托管平台跟传统的不太一样AtomGit是目前用得比较多的一个支持私有仓、权限管理还和DevEco的工具链做了些适配。先把托管这层理顺后续的版本回退、多人协作、CI流程才有底气。热更新这个话题更关键。OpenHarmony应用的发布节奏不可能像网页一样随时改随时上但业务方又经常要调样式、改文案、换图片。如果每次都重新走打包上架流程周期长、体验差。所以很多做OpenHarmony应用开发的团队都会在应用里内置一套轻量热更新机制——注意这里说的是业务内容层面的更新比如配置项、素材、样式开关这些不涉及绕过审核的整包替换。合规边界一定要把握好热更新做的是增量刷新不是规避审查。我见过不少新人在这一块踩坑一上来就想把整个Dart业务包做成动态下发结果签名校验、资源路径、加载时机全是问题。其实OpenHarmony现在的架构下最适合做的热更新是分层级的——把冷启动框架和业务资源分开框架不动业务配置走云端下发。2. AtomGit仓库配置全流程2.1 环境准备清单先把基础工具列清楚缺哪个补哪个照着执行就行。OpenHarmony SDKAPI 10及以上版本DevEco Studio里直接配置Flutter SDKOpenHarmony适配版不要用Google原版部分API实现有差异AtomGit账号支持手机号注册个人仓库免费Git2.30以上版本老版本对SSH ed25519支持不好命令行工具Windows用PowerShellmacOS用TerminalLinux随意2.2 本地工程初始化和SSH配置拿到AtomGit仓库地址后第一步是本地初始化。这里我吃过亏直接在DevEco里新建工程再关联远端经常出现分支名不一致的问题。建议用命令行先把仓库骨架拉起来。git init git remote add origin gitatomgit.com:yourname/flutter_openharmony_demo.git git add . git commit -m init: flutter openharmony demo skeletonSSH key的生成方式跟GitHub差不多但注意AtomGit的SSH端口和GitHub不一样不用改默认22就行。ssh-keygen -t ed25519 -C your_emailexample.com cat ~/.ssh/id_ed25519.pub把公钥粘贴到AtomGit后台的SSH Key管理页面。这里有个细节很多人在配置完SSH后直接push会报Permission denied (publickey)。原因多半是ssh-agent没启动或者key没加到agent里。执行一下eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519然后测试连通性ssh -T gitatomgit.com看到Welcome to AtomGit之类的提示就说明通了。2.3 分支管理和Tag规范AtomGit本身支持完整的Git能力但OpenHarmony项目版本发布有自己的一套习惯。我建议至少维护三条主线分支main主分支永远是稳定可发布状态develop开发集成分支日常提交都往这里合release/*发布分支从develop拉出来只做bug fixTag规范用v版本号_构建号比如v1.0.0_20241201。因为OpenHarmony应用有版本号、包名、签名等多重校验Tag和实际打包版本对不上后面排查问题会非常痛苦。2.4 忽略文件配置Flutter工程和原生工程混在一起后.gitignore特别容易漏配。我踩过最大的坑是构建产物被提交上去了导致仓库越来越大每次clone都要几分钟。# Flutter/Dart .dart_tool/ .packages build/ .flutter-plugins .flutter-plugins-dependencies # IDE .idea/ *.iml .vscode/ # OpenHarmony ohos/.hvigor/ ohos/oh_modules/ ohos/.cxx/有一点要格外提醒.hvigor是OpenHarmony的构建缓存目录如果被提交到远端不同开发者的本地环境一旦不同构建时会出现各种诡异错误而且很难排查。2.5 CI流程的抛砖引玉代码推上去之后建议顺手配一个简单的CI。AtomGit本身就支持Webhook可以在每次push后触发构建。我那边是先做了一个轻量的脚本拉代码、Flutter pub get、hvigor构建、把hap包归档。这一步做完后面所有的热更新测试才有稳定的产物来源。3. 热更新方案设计从原理到选型3.1 OpenHarmony应用为什么需要热更新OpenHarmony应用打包后的产物是HAP包里面包含了ArkTS代码、资源文件、配置文件等等。HAP的安装和更新走的是系统应用市场或私有分发通道周期不可控。但在实际业务里运营活动文案、首页banner图、功能开关、参数阈值这些内容变化频率远高于应用发版频率。如果每改一句文案就要重新打包发布体验太差。热更新的本质是把“不变的东西”和“常变的东西”分开管理。不变的东西打包进HAP常变的东西通过网络动态获取然后在运行时加载。3.2 三种主流热更新路径对比这里把我在实际项目中验证过的三类方案摊开来讲。方案类型更新范围实现复杂度适用场景资源级更新图片、JSON配置、字体低运营素材、参数调整字节码级更新ArkTS编译产物高业务逻辑分支调整Flutter混合更新Dart层原生资源中Flutter为主的应用资源级更新最适合起步。OpenHarmony把资源目录管理得比较清晰应用沙箱内的文件可以按需替换。做法很简单应用启动时从远端拉取资源版本的JSON清单和本地版本对比不一样就下载增量资源包解压覆盖到沙箱目录。字节码级更新比较重涉及ArkTS运行时、模块加载机制、签名校验等多个环节非必要不建议碰。而且这一块跟系统安全策略强相关不同版本的系统行为可能有差异。Flutter混合更新是咱们这个场景下的重点。Flutter应用跑在OpenHarmony上UI层是Dart渲染的逻辑层在Flutter引擎里。Dart代码被编译成内核快照资源文件和字体图片是独立存储的。这意味着如果只改UI样式、控件布局、颜色字体这类纯UI层面的东西理论上有机会通过下发新的Dart资源包来实现更新。但这个路径高度依赖Flutter引擎版本的适配情况还有打开的调试通道是否支持动态加载我在实测中稳定性只能说一般。更稳的做法是把变化部分抽成远端数据驱动比如用JSON描述页面结构Dart层只做解析渲染这样热更新的风险和成本都降到最低。3.3 我最终采用的轻量热更新架构权衡之后我的项目用了一套“配置驱动素材替换”的轻量方案。流程是这样的HAP包内置一份默认配置和默认素材启动时请求远端接口带上当前版本号远端返回最新的配置版本号和素材版本号对比本地如有差异则下载增量包下载完成后校验文件完整性更新本地沙箱数据Flutter侧通过MethodChannel读取最新配置重绘UI这套方案的好处是不碰代码编译产物不涉及签名破解完全在合规的业务逻辑内运转。风险点是远端接口必须稳定、返回值必须有严格的容错处理否则离线状态下应用会闪白。3.4 版本控制的关键设计热更新最怕的就是版本乱。我见过有人直接把配置文件传到服务器上覆盖着用出了线上问题根本不知道线上跑的是哪版。建议至少做三个字段的版本管理{ app_version: 1.0.0, config_version: 20241201_01, material_version: 20241201_01 }app_version对应HAP包的版本config_version对应配置的版本material_version对应素材包的版本。远端下发逻辑要做灰度策略先给内部测试设备推再给5%用户推确认没问题后再全量。AtomGit仓库里可以建一个release_config_beta分支专门存灰度配置验证完合入主分支。4. 实战示例一个带热更新能力的Flutter页面4.1 示例功能说明这个示例做一个简单的欢迎页页面上有一个标题、一张副标题、一张背景图。标题文案、副标题文案、背景图URL全部由远端配置控制。应用首次启动时尝试拉取远端配置拉取成功则按远端配置显示拉取失败则用本地兜底配置。4.2 工程结构flutter_openharmony_demo/ ├── lib/ │ ├── main.dart │ ├── config/ │ │ ├── local_config.dart │ │ └── remote_config.dart │ └── pages/ │ └── welcome_page.dart ├── ohos/ │ └── entry/src/main/ │ ├── ets/ │ │ └── entryability/ │ │ └── EntryAbility.ets │ └── resources/ │ └── base/ │ └── media/ │ └── default_bg.png └── pubspec.yaml4.3 Flutter侧核心代码本地配置类负责兜底逻辑class LocalConfig { static const String defaultTitle 欢迎使用 OpenHarmony; static const String defaultSubtitle Flutter 适配示例; static const String defaultBgUrl ; static const String bgAssetPath assets/default_bg.png; }远端配置类解析服务端返回的JSONclass RemoteConfig { final String title; final String subtitle; final String bgUrl; final String configVersion; RemoteConfig({ required this.title, required this.subtitle, required this.bgUrl, required this.configVersion, }); factory RemoteConfig.fromJson(MapString, dynamic json) { return RemoteConfig( title: json[title] ?? , subtitle: json[subtitle] ?? , bgUrl: json[bgUrl] ?? , configVersion: json[config_version] ?? , ); } }页面层做本地和远端的合并渲染class WelcomePage extends StatefulWidget { const WelcomePage({super.key}); override StateWelcomePage createState() _WelcomePageState(); } class _WelcomePageState extends StateWelcomePage { late RemoteConfig _remoteConfig; bool _hasRemoteConfig false; override void initState() { super.initState(); _remoteConfig RemoteConfig( title: LocalConfig.defaultTitle, subtitle: LocalConfig.defaultSubtitle, bgUrl: LocalConfig.defaultBgUrl, configVersion: 0, ); _loadRemoteConfig(); } Futurevoid _loadRemoteConfig() async { try { final config await RemoteConfigService.fetchConfig(); if (config ! null) { setState(() { _remoteConfig config; _hasRemoteConfig true; }); } } catch (e) { // 拉取失败不处理继续用本地配置 debugPrint(remote config fetch failed: $e); } } override Widget build(BuildContext context) { return Scaffold( body: Container( decoration: BoxDecoration( image: DecorationImage( image: _hasRemoteConfig _remoteConfig.bgUrl.isNotEmpty ? NetworkImage(_remoteConfig.bgUrl) : AssetImage(LocalConfig.bgAssetPath) as ImageProvider, fit: BoxFit.cover, ), ), child: Center( child: Column( mainAxisAlignment: MainAxisAlignment.center, children: [ Text( _remoteConfig.title, style: const TextStyle(fontSize: 28, fontWeight: FontWeight.bold), ), const SizedBox(height: 12), Text( _remoteConfig.subtitle, style: const TextStyle(fontSize: 16), ), ], ), ), ), ); } }RemoteConfigService的fetchConfig方法内部通过MethodChannel调用原生侧的网络请求能力解析返回JSON。OpenHarmony的Flutter适配对dart:io的http库支持不算完善建议走MethodChannel让原生层做网络请求Flutter侧只处理解析和渲染稳定很多。4.4 OpenHarmony原生侧配置加载原生侧的核心工作是用Ability的上下文从沙箱里读配置文件。我这边用了一个简单粗暴但稳定的方式把配置文件放在应用的files目录下首次启动从rawfile拷贝默认配置进去之后热更新就替换这个文件。import { fileIo } from kit.CoreFileKit; import { common } from kit.AbilityKit; function loadConfigFromFile(context: common.UIAbilityContext): string { const filesDir context.filesDir; const configPath filesDir /remote_config.json; try { const file fileIo.openSync(configPath, fileIo.OpenMode.READ_ONLY); const stat fileIo.statSync(configPath); const buf new ArrayBuffer(stat.size); fileIo.readSync(file.fd, buf); fileIo.closeSync(file); return String.fromCharCode(...new Uint8Array(buf)); } catch (e) { // 文件不存在时返回兜底配置 return JSON.stringify({ title: 欢迎使用 OpenHarmony, subtitle: 本地兜底配置, bgUrl: , config_version: local }); } }网络请求部分就不贴了原生侧用ohos.net.http模块发GET请求就行返回的JSON字符串通过MethodChannel回传给Flutter侧。4.5 热更新内容的应用端验证配置从远端拉下来了怎么确认真的生效了我的建议是在配置文件里加一个debug_mode字段值为true时在页面上渲染一个小的版本角标显示当前配置的版本号和拉取时间。这样在测试阶段一目了然知道当前跑的是哪份配置、是不是新的。等这个配置稳定了再关掉debug_mode。4.6 操作流程整个流程走一遍把示范工程推到AtomGit仓库的develop分支构建HAP包安装到开发设备打开应用确认显示“本地兜底配置”在AtomGit仓库的配置文件里改标题为“远端配置已生效”提交并推送手动触发一次远端构建部署配置文件到测试服务杀掉应用重新启动观察到页面标题变化这套流程里比较顺的一点是AtomGit的Webhook可以在配置变更后触发一个脚本脚本把配置文件推送到CDN或者对象存储上应用端只需要关注配置版本号即可。5. 常见问题与排障手记5.1 AtomGit同步慢或超时排除网络原因后最常见的坑是仓库里有大文件。构建产物里hvigor的中间文件动辄几百MB如果没ignore干净clone的时候会卡到怀疑人生。先检查仓库大小git count-objects -vH如果发现size-pack特别大用git filter-branch清理历史中的大文件再重新push。5.2 Flutter侧加载远程图片失败OpenHarmony适配版的FlutterNetworkImage默认走的是Dart侧的HTTP栈这个栈在OpenHarmony上经常被系统网络权限拦一道。排查三步走检查应用的module.json5里有没有声明ohos.permission.INTERNET用原生侧的网络请求试试同一个URL确认是Flutter的问题还是系统权限的问题如果是Flutter的HTTP栈问题改用MethodChannel原生侧下载图片后转Base64回传给Flutter或者直接保存到沙箱用FileImage加载5.3 热更新后UI没变化配置确实下载了文件也替换了但界面没动静。大概率是Widget没有重建。注意我用的是setState触发重建如果你的业务里更新完配置后停留在当前页面记得在最外层包一层ValueListenableBuilder或者手动调用setState。不要在initState里做异步加载然后不更新状态这是Flutter新手最常见的静态UI病根。5.4 版本号比较逻辑混乱我踩过一次比较大的坑配置版本号用字符串比较结果20241202_1和20241202_10比较时字符串顺序不对导致永远拉不到最新配置。后来统一改成纯数字时间戳或者递增整数比较逻辑才稳下来。版本号格式越简单越不容易出错。5.5 缓存导致的“假更新”联调时经常出现改了配置但客户端好像还是旧的——其实是HTTP缓存或者沙箱缓存。解决方法是请求时带随机query参数或者在配置文件里加一个随机字符串字段参与完整性校验从源头消灭缓存命中的可能。6. 实际体会和后续思路这套流程跑通之后我最大的感受是OpenHarmony生态的工具链虽然不如安卓那边成熟但该有的零件都在拼凑起来也就是一个晚上的事。热更新这块千万别想着一步到位做全量动态化从配置和素材入手风险小、见效快。等团队对OpenHarmony的运行机制吃透了再考虑要不要往更深的层级走。后续我觉得可以扩展的方向有两个一个是把配置文件的内容从纯文本升级为带schema的配置这样服务端能按字段维度做灰度下发另一个是把配置拉取时机从冷启动改成前后台切换时静默更新让热更新更无感。这两个方向我都已经在试了后面跑出阶段性结果了再单独写一篇。最后再补一句代码仓库记得定期打Tag血泪教训没有Tag的历史版本出问题的时候排查成本和重新测试成本基本翻倍。
Flutter在OpenHarmony生态里跑起来这件事前一阵子折腾了不少时间。这篇是系列第二篇重点解决两个问题一个是代码仓库怎么用AtomGit搭起来另一个是OpenHarmony应用做热更新的几种常见打法。最后会带一个能直接跑的示例把配置和更新串起来看效果。适合正打算在OpenHarmony上做Flutter适配、又被仓库和更新流程卡住的开发者参考。先说下我手上这套环境设备端是OpenHarmony 4.0 Release开发框架用的是DevEco StudioFlutter SDK用的是OpenHarmony官方适配的分支版本。这个组合目前算比较稳的后面所有操作都基于这套环境。如果你还是3.2或者更早的版本建议先升级不然后面有些配置项和API对不上。1. 项目前置逻辑为什么先搞定仓库和热更新在OpenHarmony上做Flutter开发跟安卓/iOS最大的不同在于你既要管Flutter侧的Dart代码又要管OpenHarmony侧的元服务打包逻辑。很多团队第一步就卡在代码托管上——OpenHarmony生态下常用的Git托管平台跟传统的不太一样AtomGit是目前用得比较多的一个支持私有仓、权限管理还和DevEco的工具链做了些适配。先把托管这层理顺后续的版本回退、多人协作、CI流程才有底气。热更新这个话题更关键。OpenHarmony应用的发布节奏不可能像网页一样随时改随时上但业务方又经常要调样式、改文案、换图片。如果每次都重新走打包上架流程周期长、体验差。所以很多做OpenHarmony应用开发的团队都会在应用里内置一套轻量热更新机制——注意这里说的是业务内容层面的更新比如配置项、素材、样式开关这些不涉及绕过审核的整包替换。合规边界一定要把握好热更新做的是增量刷新不是规避审查。我见过不少新人在这一块踩坑一上来就想把整个Dart业务包做成动态下发结果签名校验、资源路径、加载时机全是问题。其实OpenHarmony现在的架构下最适合做的热更新是分层级的——把冷启动框架和业务资源分开框架不动业务配置走云端下发。2. AtomGit仓库配置全流程2.1 环境准备清单先把基础工具列清楚缺哪个补哪个照着执行就行。OpenHarmony SDKAPI 10及以上版本DevEco Studio里直接配置Flutter SDKOpenHarmony适配版不要用Google原版部分API实现有差异AtomGit账号支持手机号注册个人仓库免费Git2.30以上版本老版本对SSH ed25519支持不好命令行工具Windows用PowerShellmacOS用TerminalLinux随意2.2 本地工程初始化和SSH配置拿到AtomGit仓库地址后第一步是本地初始化。这里我吃过亏直接在DevEco里新建工程再关联远端经常出现分支名不一致的问题。建议用命令行先把仓库骨架拉起来。git init git remote add origin gitatomgit.com:yourname/flutter_openharmony_demo.git git add . git commit -m init: flutter openharmony demo skeletonSSH key的生成方式跟GitHub差不多但注意AtomGit的SSH端口和GitHub不一样不用改默认22就行。ssh-keygen -t ed25519 -C your_emailexample.com cat ~/.ssh/id_ed25519.pub把公钥粘贴到AtomGit后台的SSH Key管理页面。这里有个细节很多人在配置完SSH后直接push会报Permission denied (publickey)。原因多半是ssh-agent没启动或者key没加到agent里。执行一下eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519然后测试连通性ssh -T gitatomgit.com看到Welcome to AtomGit之类的提示就说明通了。2.3 分支管理和Tag规范AtomGit本身支持完整的Git能力但OpenHarmony项目版本发布有自己的一套习惯。我建议至少维护三条主线分支main主分支永远是稳定可发布状态develop开发集成分支日常提交都往这里合release/*发布分支从develop拉出来只做bug fixTag规范用v版本号_构建号比如v1.0.0_20241201。因为OpenHarmony应用有版本号、包名、签名等多重校验Tag和实际打包版本对不上后面排查问题会非常痛苦。2.4 忽略文件配置Flutter工程和原生工程混在一起后.gitignore特别容易漏配。我踩过最大的坑是构建产物被提交上去了导致仓库越来越大每次clone都要几分钟。# Flutter/Dart .dart_tool/ .packages build/ .flutter-plugins .flutter-plugins-dependencies # IDE .idea/ *.iml .vscode/ # OpenHarmony ohos/.hvigor/ ohos/oh_modules/ ohos/.cxx/有一点要格外提醒.hvigor是OpenHarmony的构建缓存目录如果被提交到远端不同开发者的本地环境一旦不同构建时会出现各种诡异错误而且很难排查。2.5 CI流程的抛砖引玉代码推上去之后建议顺手配一个简单的CI。AtomGit本身就支持Webhook可以在每次push后触发构建。我那边是先做了一个轻量的脚本拉代码、Flutter pub get、hvigor构建、把hap包归档。这一步做完后面所有的热更新测试才有稳定的产物来源。3. 热更新方案设计从原理到选型3.1 OpenHarmony应用为什么需要热更新OpenHarmony应用打包后的产物是HAP包里面包含了ArkTS代码、资源文件、配置文件等等。HAP的安装和更新走的是系统应用市场或私有分发通道周期不可控。但在实际业务里运营活动文案、首页banner图、功能开关、参数阈值这些内容变化频率远高于应用发版频率。如果每改一句文案就要重新打包发布体验太差。热更新的本质是把“不变的东西”和“常变的东西”分开管理。不变的东西打包进HAP常变的东西通过网络动态获取然后在运行时加载。3.2 三种主流热更新路径对比这里把我在实际项目中验证过的三类方案摊开来讲。方案类型更新范围实现复杂度适用场景资源级更新图片、JSON配置、字体低运营素材、参数调整字节码级更新ArkTS编译产物高业务逻辑分支调整Flutter混合更新Dart层原生资源中Flutter为主的应用资源级更新最适合起步。OpenHarmony把资源目录管理得比较清晰应用沙箱内的文件可以按需替换。做法很简单应用启动时从远端拉取资源版本的JSON清单和本地版本对比不一样就下载增量资源包解压覆盖到沙箱目录。字节码级更新比较重涉及ArkTS运行时、模块加载机制、签名校验等多个环节非必要不建议碰。而且这一块跟系统安全策略强相关不同版本的系统行为可能有差异。Flutter混合更新是咱们这个场景下的重点。Flutter应用跑在OpenHarmony上UI层是Dart渲染的逻辑层在Flutter引擎里。Dart代码被编译成内核快照资源文件和字体图片是独立存储的。这意味着如果只改UI样式、控件布局、颜色字体这类纯UI层面的东西理论上有机会通过下发新的Dart资源包来实现更新。但这个路径高度依赖Flutter引擎版本的适配情况还有打开的调试通道是否支持动态加载我在实测中稳定性只能说一般。更稳的做法是把变化部分抽成远端数据驱动比如用JSON描述页面结构Dart层只做解析渲染这样热更新的风险和成本都降到最低。3.3 我最终采用的轻量热更新架构权衡之后我的项目用了一套“配置驱动素材替换”的轻量方案。流程是这样的HAP包内置一份默认配置和默认素材启动时请求远端接口带上当前版本号远端返回最新的配置版本号和素材版本号对比本地如有差异则下载增量包下载完成后校验文件完整性更新本地沙箱数据Flutter侧通过MethodChannel读取最新配置重绘UI这套方案的好处是不碰代码编译产物不涉及签名破解完全在合规的业务逻辑内运转。风险点是远端接口必须稳定、返回值必须有严格的容错处理否则离线状态下应用会闪白。3.4 版本控制的关键设计热更新最怕的就是版本乱。我见过有人直接把配置文件传到服务器上覆盖着用出了线上问题根本不知道线上跑的是哪版。建议至少做三个字段的版本管理{ app_version: 1.0.0, config_version: 20241201_01, material_version: 20241201_01 }app_version对应HAP包的版本config_version对应配置的版本material_version对应素材包的版本。远端下发逻辑要做灰度策略先给内部测试设备推再给5%用户推确认没问题后再全量。AtomGit仓库里可以建一个release_config_beta分支专门存灰度配置验证完合入主分支。4. 实战示例一个带热更新能力的Flutter页面4.1 示例功能说明这个示例做一个简单的欢迎页页面上有一个标题、一张副标题、一张背景图。标题文案、副标题文案、背景图URL全部由远端配置控制。应用首次启动时尝试拉取远端配置拉取成功则按远端配置显示拉取失败则用本地兜底配置。4.2 工程结构flutter_openharmony_demo/ ├── lib/ │ ├── main.dart │ ├── config/ │ │ ├── local_config.dart │ │ └── remote_config.dart │ └── pages/ │ └── welcome_page.dart ├── ohos/ │ └── entry/src/main/ │ ├── ets/ │ │ └── entryability/ │ │ └── EntryAbility.ets │ └── resources/ │ └── base/ │ └── media/ │ └── default_bg.png └── pubspec.yaml4.3 Flutter侧核心代码本地配置类负责兜底逻辑class LocalConfig { static const String defaultTitle 欢迎使用 OpenHarmony; static const String defaultSubtitle Flutter 适配示例; static const String defaultBgUrl ; static const String bgAssetPath assets/default_bg.png; }远端配置类解析服务端返回的JSONclass RemoteConfig { final String title; final String subtitle; final String bgUrl; final String configVersion; RemoteConfig({ required this.title, required this.subtitle, required this.bgUrl, required this.configVersion, }); factory RemoteConfig.fromJson(MapString, dynamic json) { return RemoteConfig( title: json[title] ?? , subtitle: json[subtitle] ?? , bgUrl: json[bgUrl] ?? , configVersion: json[config_version] ?? , ); } }页面层做本地和远端的合并渲染class WelcomePage extends StatefulWidget { const WelcomePage({super.key}); override StateWelcomePage createState() _WelcomePageState(); } class _WelcomePageState extends StateWelcomePage { late RemoteConfig _remoteConfig; bool _hasRemoteConfig false; override void initState() { super.initState(); _remoteConfig RemoteConfig( title: LocalConfig.defaultTitle, subtitle: LocalConfig.defaultSubtitle, bgUrl: LocalConfig.defaultBgUrl, configVersion: 0, ); _loadRemoteConfig(); } Futurevoid _loadRemoteConfig() async { try { final config await RemoteConfigService.fetchConfig(); if (config ! null) { setState(() { _remoteConfig config; _hasRemoteConfig true; }); } } catch (e) { // 拉取失败不处理继续用本地配置 debugPrint(remote config fetch failed: $e); } } override Widget build(BuildContext context) { return Scaffold( body: Container( decoration: BoxDecoration( image: DecorationImage( image: _hasRemoteConfig _remoteConfig.bgUrl.isNotEmpty ? NetworkImage(_remoteConfig.bgUrl) : AssetImage(LocalConfig.bgAssetPath) as ImageProvider, fit: BoxFit.cover, ), ), child: Center( child: Column( mainAxisAlignment: MainAxisAlignment.center, children: [ Text( _remoteConfig.title, style: const TextStyle(fontSize: 28, fontWeight: FontWeight.bold), ), const SizedBox(height: 12), Text( _remoteConfig.subtitle, style: const TextStyle(fontSize: 16), ), ], ), ), ), ); } }RemoteConfigService的fetchConfig方法内部通过MethodChannel调用原生侧的网络请求能力解析返回JSON。OpenHarmony的Flutter适配对dart:io的http库支持不算完善建议走MethodChannel让原生层做网络请求Flutter侧只处理解析和渲染稳定很多。4.4 OpenHarmony原生侧配置加载原生侧的核心工作是用Ability的上下文从沙箱里读配置文件。我这边用了一个简单粗暴但稳定的方式把配置文件放在应用的files目录下首次启动从rawfile拷贝默认配置进去之后热更新就替换这个文件。import { fileIo } from kit.CoreFileKit; import { common } from kit.AbilityKit; function loadConfigFromFile(context: common.UIAbilityContext): string { const filesDir context.filesDir; const configPath filesDir /remote_config.json; try { const file fileIo.openSync(configPath, fileIo.OpenMode.READ_ONLY); const stat fileIo.statSync(configPath); const buf new ArrayBuffer(stat.size); fileIo.readSync(file.fd, buf); fileIo.closeSync(file); return String.fromCharCode(...new Uint8Array(buf)); } catch (e) { // 文件不存在时返回兜底配置 return JSON.stringify({ title: 欢迎使用 OpenHarmony, subtitle: 本地兜底配置, bgUrl: , config_version: local }); } }网络请求部分就不贴了原生侧用ohos.net.http模块发GET请求就行返回的JSON字符串通过MethodChannel回传给Flutter侧。4.5 热更新内容的应用端验证配置从远端拉下来了怎么确认真的生效了我的建议是在配置文件里加一个debug_mode字段值为true时在页面上渲染一个小的版本角标显示当前配置的版本号和拉取时间。这样在测试阶段一目了然知道当前跑的是哪份配置、是不是新的。等这个配置稳定了再关掉debug_mode。4.6 操作流程整个流程走一遍把示范工程推到AtomGit仓库的develop分支构建HAP包安装到开发设备打开应用确认显示“本地兜底配置”在AtomGit仓库的配置文件里改标题为“远端配置已生效”提交并推送手动触发一次远端构建部署配置文件到测试服务杀掉应用重新启动观察到页面标题变化这套流程里比较顺的一点是AtomGit的Webhook可以在配置变更后触发一个脚本脚本把配置文件推送到CDN或者对象存储上应用端只需要关注配置版本号即可。5. 常见问题与排障手记5.1 AtomGit同步慢或超时排除网络原因后最常见的坑是仓库里有大文件。构建产物里hvigor的中间文件动辄几百MB如果没ignore干净clone的时候会卡到怀疑人生。先检查仓库大小git count-objects -vH如果发现size-pack特别大用git filter-branch清理历史中的大文件再重新push。5.2 Flutter侧加载远程图片失败OpenHarmony适配版的FlutterNetworkImage默认走的是Dart侧的HTTP栈这个栈在OpenHarmony上经常被系统网络权限拦一道。排查三步走检查应用的module.json5里有没有声明ohos.permission.INTERNET用原生侧的网络请求试试同一个URL确认是Flutter的问题还是系统权限的问题如果是Flutter的HTTP栈问题改用MethodChannel原生侧下载图片后转Base64回传给Flutter或者直接保存到沙箱用FileImage加载5.3 热更新后UI没变化配置确实下载了文件也替换了但界面没动静。大概率是Widget没有重建。注意我用的是setState触发重建如果你的业务里更新完配置后停留在当前页面记得在最外层包一层ValueListenableBuilder或者手动调用setState。不要在initState里做异步加载然后不更新状态这是Flutter新手最常见的静态UI病根。5.4 版本号比较逻辑混乱我踩过一次比较大的坑配置版本号用字符串比较结果20241202_1和20241202_10比较时字符串顺序不对导致永远拉不到最新配置。后来统一改成纯数字时间戳或者递增整数比较逻辑才稳下来。版本号格式越简单越不容易出错。5.5 缓存导致的“假更新”联调时经常出现改了配置但客户端好像还是旧的——其实是HTTP缓存或者沙箱缓存。解决方法是请求时带随机query参数或者在配置文件里加一个随机字符串字段参与完整性校验从源头消灭缓存命中的可能。6. 实际体会和后续思路这套流程跑通之后我最大的感受是OpenHarmony生态的工具链虽然不如安卓那边成熟但该有的零件都在拼凑起来也就是一个晚上的事。热更新这块千万别想着一步到位做全量动态化从配置和素材入手风险小、见效快。等团队对OpenHarmony的运行机制吃透了再考虑要不要往更深的层级走。后续我觉得可以扩展的方向有两个一个是把配置文件的内容从纯文本升级为带schema的配置这样服务端能按字段维度做灰度下发另一个是把配置拉取时机从冷启动改成前后台切换时静默更新让热更新更无感。这两个方向我都已经在试了后面跑出阶段性结果了再单独写一篇。最后再补一句代码仓库记得定期打Tag血泪教训没有Tag的历史版本出问题的时候排查成本和重新测试成本基本翻倍。
