1. 为什么 flutter_app_icon 值得做鸿蒙适配
1.1 这个库原本解决了什么问题
做 Flutter 开发的人应该都经历过这种痛：产品经理一句“换个图标吧”，接下来就是整整半天的机械劳动。一套源图要切出 Android 的 mdpi、hdpi、xhdpi、xxhdpi、xxxhdpi，还要处理 iOS 的 20pt、29pt、40pt、60pt、76pt、83.5pt 各种倍率，稍微粗心一点就会漏掉某个尺寸，上架审核被打回。flutter_app_icon 就是专门解决这个抱怨的第三方命令行工具，它基于 Dart 编写，核心逻辑很简单：你给它一张 1024x1024 的源图，它在本地自动完成缩放、裁剪、产出全套多端图标文件，并且直接覆盖到对应平台的资源目录里。
老实说，这个库在 Android/iOS/Web 场景下已经相当成熟，社区里很多人把它接进了自己的 Flutter 工程，配合 Fastlane 或者 GitHub Actions 做版本发布。但问题来了：这两年 OpenHarmony 设备越来越多，鸿蒙应用开发也成为很多团队的必选项，这时候 flutter_app_icon 就“哑火”了。它生成的资源目录里根本没有 ohos 这一项，鸿蒙工程只能手动去切一套图标，之前的自动化优势瞬间归零。我这次做的事情，就是给这个老牌工具接上 OpenHarmony 的“后半程”，让它能把一套源图同时输出到 Android、iOS、Web 以及鸿蒙工程目录，补齐自动化视觉资产部署的最后一环。
1.2 鸿蒙应用图标的规格究竟特殊在哪
很多人以为鸿蒙图标无非就是“方形的 PNG 资源”，直接把 Android 的 ic_launcher.png 改名拷过去就行，实际上这个想法会栽大跟头。OpenHarmony 的应用图标体系跟 Android 的 legacy icon 逻辑不一样，它更接近 Android 8.0 之后的 Adaptive Icon 思路，但又加了自家规则。
鸿蒙图标通常由两张图组成：一张是前台图层，也就是用户实际看到的图形主体，比如一个猫头、一个盾牌、一个字母；另一张是背景图层，作为整个图标的底色或者场景。系统会把这两张图叠起来渲染，同时在不同设备、不同桌面形态下还会做视差、缩放、遮罩处理。如果不分前景背景直接压一张整图进去，轻则桌面显示裁切怪异，重则华为应用市场上传时直接被驳回。加上鸿蒙对不同屏幕密度有一套自己的像素档位要求，并不完全和 Android 的 mipmap 目录一一对应，这就导致“复制粘贴”式的移植思路几乎走不通。
1.3 官方 Flutter 工具链目前留下的空缺
说到这必须提一句，Flutter 官方对 OpenHarmony 的支持这几年进步很明显，从最早只存在于开源社区的分支版本，到后来 DevEco Studio 与 Flutter SDK 联动，再到现在的 ohos 目录原生嵌入工程模板，整体开发体验已经比较接近 Android/iOS 双端。但注意，官方框架解决的是“Flutter 引擎能在鸿蒙上跑起来、Widget 能渲染、插件能桥接”这类基础问题，它不会替你处理素材生产。
也就是说，你的 Flutter 工程里即使有 ohos 目录，Xcode 有 AppIcon.appiconset、Android 有 mipmap 系列，鸿蒙侧的图标资源仍然需要手动收集、裁剪、放路径。如果团队里只有一两个会切图的人，这个环节几乎必然成为发版瓶颈。当初我接手团队的发版流水线时，就眼睁睁看着同事用 PS 一张张导出鸿蒙图标，导完还要手动改文件名核对尺寸，既慢又容易出错。所以把 flutter_app_icon 的生成逻辑扩展出一套鸿蒙分支，本质上是在填补官方的“素材生产自动化”空白，属于非常典型且高 ROI 的适配工作。
2. 适配之前的工程结构与环境摸底
2.1 先认清 Flutter 工程在 OpenHarmony 下的目录形态
动手改代码之前，我建议你先把自己手上的 Flutter 工程翻出来看一遍，确认它到底处于哪个演进阶段。早年做鸿蒙适配，普遍做法是拉一个flutter_flutter的 OpenHarmony 分支，或者把ohos目录手工塞进工程根目录，里面的结构跟现在官方模板差异不小。而现阶段比较标准的 Flutter 工程，在pubspec.yaml同级目录下会存在ohos/文件夹，内部大体的目录结构长这样：
ohos/ ├── entry/ │ └── src/ │ └── main/ │ ├── module.json5 │ ├── resources/ │ │ ├── base/ │ │ │ ├── element/ │ │ │ ├── media/ │ │ │ └── profile/ │ │ └── rawfile/ │ └── ets/ └── ...其中module.json5是鸿蒙模块的配置文件，类似 Android 的 AndroidManifest.xml，应用图标引用关系就在这里面声明。resources/base/media是放置图标等位图资源的常用目录，不过鸿蒙允许你按限定词建子目录，比如media.en_US或者media.arkui，只是默认工程一般只用base一套。搞清楚这个目录形态，后面生成器输出文件才放得准。
2.2 图标资源在鸿蒙工程里的真实映射位置
这一步是关键中的关键，也是我最早踩坑的地方。很多 Flutter 工程师习惯了 Android 的android/app/src/main/res/mipmap-*和 iOS 的Assets.xcassets，以为鸿蒙也是类似逻辑，把图标往某个目录一丢就行。实际上鸿蒙的图标资源映射，核心入口在module.json5里通过abilities节点表示。
举个例子：应用入口模块里一般会有"icon": "$media:layered_icon"这样的字段，它指向的不是一个具体的 PNG 文件，而是一个逻辑资源名称。这个layered_icon需要能在resources/base/media下找到同名资源，或者通过resources/base/element里的 JSON 去解析多图层引用。如果 flutter_app_icon 生成的输出文件叫ic_launcher.png而 module.json5 指向layered_icon，哪怕文件躺在正确目录里也不会生效。
所以适配时，我们要做的不是简单“往 ohos 目录丢几个 PNG”，而是同步处理好三层关系：文件生成位置、文件命名规则、module.json5 的引用指向。这三层没对齐，打包能过，但装到手机上图标就是默认的灰色方块，排查起来很容易让人抓狂。
2.3 工具链与环境版本怎么选
接下来是你本机需要准备的东西。这里我列一个我实测过能稳定工作的组合，不一定要求大家完全照搬，但至少可以帮你少走弯路：
| 工具 | 建议版本 | 说明 |
|---|---|---|
| Flutter SDK | 3.7 及以上，支持 ohos 模板 | 越低版本对 OpenHarmony 目录支持越差 |
| Dart SDK | 随 Flutter 内置即可 | flutter_app_icon 本身是 Dart 写的，直接跑脚本 |
| Node.js | 16 以上 | 部分自动化流水线需要用到脚本触发 |
| DevEco Studio | 4.0 及以上 | 用于最终打包 HAP 验证图标生效情况 |
| OpenHarmony SDK | API 9 及以上 | API 版本影响 module.json5 字段，注意区分 |
版本选择背后有一个实际考虑：flutter_app_icon 过去主要生成 Android/iOS 资源，它内部对“端”的判断是枚举写死的。适配鸿蒙时如果 Flutter 版本本身不支持 ohos 目录，工具就算生成了文件，放进工程也未必被 DevEco 的编译链路识别。反过来，用太新的 Flutter SDK 但又拉了一个老版本的分支 flutter_app_icon，Dart 语法兼容也可能出问题。我建议优先把自己工程的 Flutter 版本确认清楚再改代码，否则容易陷入“代码没问题但构建失败”的鬼打墙。
2.4 准备一份合格的源图
在动手改代码之前，还要确认一件事：源图质量。flutter_app_icon 本质上是“缩放器”，它不会帮你提升原始素材的清晰度。如果你喂给它的源图是 512x512 的 JPEG，那生成鸿蒙的大尺寸图标时必然发虚；如果源图带着透明通道但内容本身没有撑满安全区，烘托出来的前景背景比例也会很怪。
我个人的实践经验是：源图至少准备 1024x1024 的 PNG，并且把“视觉主体”控制在中心半径 50% 的圆形区域内。这样做不是为了迎合 flutter_app_icon，而是因为鸿蒙桌面图标会在前景层做缩放和视差处理，主体太靠近边缘，用户转动设备或者系统渲染视差时很容易产生裁切感，观感一下就廉价了。确认源图满足要求后，再进入正式改造环节。
3. flutter_app_icon 鸿蒙适配改造：从源码到本地验证
3.1 克隆仓库并定位图标生成核心逻辑
万事俱备，接下来进入正题。先把 flutter_app_icon 仓库克隆到本地，我一般习惯用一个干净的临时目录试跑，不直接动现有工程。
git clone https://github.com/flutter-app-icon/flutter_app_icon.git cd flutter_app_icon打开项目目录后，不用管那些 example 和多语言的 README，真正要关注的是lib源码目录。核心逻辑通常在类似lib/src/icon_generator.dart或者lib/src/generator.dart的文件里，里面定义了所有平台图标规格的映射关系。你可以用关键字mipmap、AppIcon、android去搜，快速定位到生成目标的枚举和尺寸表。
这个文件里会有一个大的 Map 或者 switch 分支，分别列出 Android 的mipmap-mdpi、mipmap-hdpi等目录，以及对应的像素尺寸。我们的目标很明确：在这个表里加入ohos相关条目，并让生成主流程在解析目标平台时认识ohos这个新成员。听起来简单，但具体添加的位置和命名规则必须看懂了再动，否则会碰到“生成器不认识新平台”的异常。
3.2 把“生成目标”里加进 ohos：注册尺寸表
现在来看我具体怎么改。找到类似IconGenerator的类后，里面通常会有一个类似getIconSpecs的方法，返回各平台尺寸规格。
Map<String, List<int>> getIconSpecs(PlatformType platform) { switch (platform) { case PlatformType.android: return { 'mipmap-mdpi': 48, 'mipmap-hdpi': 72, 'mipmap-xhdpi': 96, 'mipmap-xxhdpi': 144, 'mipmap-xxxhdpi': 192, }; case PlatformType.ios: return { 'AppIcon.appiconset/Icon-60@2x.png': 120, // ... }; } }我在这里加了一个PlatformType.ohos分支，尺寸表参照了 OpenHarmony 对应用图标的建议档位：前景和背景各自生成 48、72、96、144、192 这五个尺寸。这么做有一个直观好处：鸿蒙图标在手机、平板、折叠屏上的显示基本覆盖到了，而且与 Android 的 mdpi 到 xxxhdpi 一一对应，后续写脚本时心智负担最小。
case PlatformType.ohos: return { 'foreground/ohos_icon_foreground_48.png': 48, 'foreground/ohos_icon_foreground_72.png': 72, // ... 'background/ohos_icon_background_192.png': 192, };为什么这里要区分 foreground 和 background 子目录？直接拍平放在一个media目录不行吗？前面说过，鸿蒙系统渲染的是图层叠加。如果所有尺寸、所有图层全丢在一个目录里，资源打包可以过，但模块配置没法引用独立图层；就算 module.json5 配好了，桌面上看起来也是少了层次感。尤其是当背景是一张纯色或者渐变图、前景是透明 PNG 时，只有分目录输出才能保证后期替换、换肤、主题适配更灵活。这个设计不是拍脑袋，而是顺着 OpenHarmony 资源管理的习惯走的。
3.3 让生成器按鸿蒙规则分前景、背景输出
光有尺寸表还不够，还得让实际写文件部分的代码知道：生成ohos平台时，要把源图略作内缩处理后写成前景层，把原图或者缩放后的底色写成背景层。
flutter_app_icon 底层一般是复用image包来做解码和缩放。我改造的逻辑大致是这样：
- 读取源图（1024x1024 PNG）。
- 复制一份作为前景图：按尺寸缩放，但把画布扩大到 1.2 倍，保持主体居中。这一步是模仿鸿蒙前景层的安全区处理逻辑，避免生成的图标在桌面视差效果下出现过窄的安全余量。
- 复制另一份作为背景图：如果源图本身是一个带背景的完整图标，就直接缩放；如果源图是透明底，就生成一个与背景色一致的纯色画布（颜色可以在命令行参数里指定）。
- 按照
ohosIconSpecs里的尺寸表，循环生成所有 PNG 文件，输出到ohos/entry/src/main/resources/base/media/下的对应子目录。
await _generateOhosIcons( sourceImage: decodedImage, outputDir: ohosMediaDir, backgroundColor: const Color(0xFF111111), );这里我强烈建议在改造时不要去动 Android/iOS 原来的生成逻辑，额外加一个独立方法处理 ohos，避免破坏现有用户的使用习惯。如果你把源码推回给上游，维护者也会更倾向于接受这种“新增平台分支”而不是“重构原有逻辑”的提交。
3.4 命名与目录规范：避免 build 阶段踩命名坑
写文件这部分还有一个极其容易翻车的点：资源命名。OpenHarmony 的资源命名不像 Android 那样几乎任意小写字母、数字、下划线都行，它更严格。文件名不能以数字开头，不要包含大写字母，不能用横杠，也不要出现.9.png这类 Android 独有格式。之前看到有人把生成文件命名为Icon-192.png，结果 DevEco Studio 编译时提示资源名非法，打包直接中断。
我最终的命名方案是：统一前缀ohos_icon_，中缀区分foreground/background，后缀是像素尺寸，比如ohos_icon_foreground_192.png、ohos_icon_background_192.png。这样的好处有三个：第一，全部小写且无非法字符，DevEco 不会有脾气；第二，文件名自解释，后续同事看到目录不用猜；第三，排序规整，在文件管理器里人工检查时一目了然。
对应地，module.json5里的图标引用也要调整。如果entry模块使用了layered_icon作为逻辑名，我建议直接改成引用具体的 media 资源名，避免额外维护一套element解析链。例如：
"icon": "$media:ohos_icon_foreground_192",背景层则在资源配置或者坚守默认系统背景之间取舍。如果你的前景图本身自带背景，甚至可以只引用前景层、背景留空，让系统垫默认色，这样上架审核也不会挑毛病。
3.5 本地跑通：一条命令生成四端图标
改造完成之后，最激动人心的时刻就是用命令行实测。flutter_app_icon 通常支持通过dart run直接执行入口文件，也能注册成flutter_app_icon命令。我的用法是在项目根目录准备好icon_source.png，然后执行：
dart run flutter_app_icon --source=icon_source.png --platforms=android,ios,ohos执行完毕后检查目录输出。正常情况下，ohos/entry/src/main/resources/base/media/下会出现我们定义的前景、背景两组文件，同时原来的 android 和 ios 资源也一并更新。这一步能跑通，说明本地改造基本完成。
随后打开 DevEco Studio 编译一个 HAP 包，安装到模拟器或者真机上，观察桌面图标显示效果。这里要特别提醒：模拟器上图标缓存很顽固，有时候即使文件替换了、包也重装了，桌面依然显示旧图标。我一般会先卸载应用、清掉 Launcher 缓存，再重新安装验证，否则容易误判成“生成无效”，实际只是缓存没刷新。
4. 在 OpenHarmony 上打造自动化视觉资产部署实战
4.1 最轻量的接入方式：把生成脚本挂进打包命令
改造完 flutter_app_icon 之后，它就不再是“一次性工具”了，而应该变成你工程里员日常打包流程的一部分。最轻量的接入方式是写一个本地 Shell 脚本，放在工程根目录下的tool/文件夹里，每次打包前先跑一遍图标生成。
#!/bin/bash set -e ICON_SOURCE="${ICON_SOURCE:-assets/app_icon.png}" FLUTTER_APP_ICON_CMD="dart run flutter_app_icon" $FLUTTER_APP_ICON_CMD \ --source="$ICON_SOURCE" \ --platforms=android,ios,ohos \ --backgroundColor="#111111" echo "icons refreshed at $(date)"然后在 DevEco Studio 的构建任务或者你脚手的 HAP 打包脚本里，把这段脚本放在编译之前。这样每次更换图标素材，团队只需要替换assets/app_icon.png一个文件，剩下的尺寸切割、目录拷贝、命名对齐全部自动完成。
我个人的体会是，这个阶段不要追求“一键全自动”，先把流程跑通最重要。因为一旦脚本前置到打包链路里，它就成为所有开发者共享的“基础设施”，如果中间出 bug，比如输出目录写错、图片尺寸异常，会直接卡住全团队的打包。所以初期我情愿多手动验证几轮，也要保证脚本的幂等性：无论跑多少遍，产出的文件内容一致，不会越跑越乱。
4.2 在 CI/CD 流水线里跑图标生成与校验
本地跑通之后，就该把图标生成接入 CI/CD 了。以 GitHub Actions 为例，我在流水线上增加一个 job，专门负责视觉资产刷新和校验。这个 job 做的事情很单纯：检查源图的哈希值是否有变化，有变化才跑生成器，避免多余的文件改动污染提交记录。
核心思路是：用git diff判断assets/app_icon.png是否被修改，如果修改了，就执行dart run flutter_app_icon，然后把生成的ohos/、android/、ios/资源一并提交回仓库。如果源图没变，直接跳过生成步骤，保留上一次的资源产物。这样做的好处是不会让 CI 每次构建都产生无意义的文件变更，也方便审查人员快速看出一次改动到底影响了哪些端。
流水线里还应该加一个资源校验动作：检查关键文件是否存在，并且尺寸符合预期。我在 CI 脚本里用了 ImageMagick 的identify命令做快速核对：
identify -format "%w x %h %f\n" \ ohos/entry/src/main/resources/base/media/foreground/*.png \ ohos/entry/src/main/resources/base/media/background/*.png尺寸不对或者文件缺失，CI 直接 fail，不给问题图标进入正式包的机会。实测下来这个步骤特别管用，能把“同事忘跑脚本直接提交代码”这类低级失误拦截住。
4.3 资源缓存、增量构建与幂等性设计
自动化部署过程中，最容易被忽略的是缓存和幂等性。OpenHarmony 的 DevEco Studio 构建系统会缓存资源处理结果，如果你只是覆盖了 PNG 文件，但文件名和路径没变，构建系统可能以为资源没更新，直接把旧的打包进 HAP。这时候就算源图换成了新图标，最终产物依然显示旧图。
针对这个问题，我用的手段有两个。第一，生成新图标后，主动 touch 一下module.json5，改变文件的修改时间，让构建系统意识到配置有变化，进而触发资源重新解析。第二，在脚本里输出一份icon_version.txt，内容是一个自增序号或者源图 MD5，同时把这个版本号注到模块配置里，确保每次内容不同时产物也会不同。
echo "# $(md5sum assets/app_icon.png)" > ohos/entry/src/main/resources/base/media/icon_version.txt这个文件虽然不会被安装包使用，但它能作为构建链路上的“噪音发生器”，让 DevEco 重新评估资源目录。实际效果非常明显，至少我在真机测试中没有再遇到过“图标不刷新”的情况。
还有一个小细节：不要在 CI 里使用当前时间作为版本号，否则同一份源图会在每次构建时生成不同元数据，破坏可重复构建。用源图哈希最稳，因为内容不变就不应该产生新的构建差异。
5. 常见问题与排查技巧实录
5.1 图标生成后桌面显示的还是旧图
这个坑我排了很久，最后定位到两个原因。一是构建缓存，这在 4.3 里已经说过，通过 touchmodule.json5或者改写版本文件能强制刷新。二是设置里可能开了“默认图标”模式，某些设备主题或者开发者选项会把应用图标强制成系统默认样式，尤其是从 beta 版本 OpenHarmony 刷过来的设备更容易出现。验证方法也很简单：去设置里搜索“图标”，或者重新应用一次浅色/深色主题，如果图标恢复了，就说明不是资源生成问题而是系统显示问题。
5.2 图标发虚、边缘锯齿
大多数情况下，发虚都是源图分辨率不够导致的。flutter_app_icon 再强大也只是缩放器，216 像素的源图强行拉到 192 甚至 1024 档位，不虚才怪。建议回炉素材，换成 AI 或者矢量稿导出一份 1024x1024 的图。还有一种情况比较隐蔽：源图是 JPG 格式，JPG 的压缩噪点在放大后会被边缘检测放大，视觉上像“毛刺”。解决方法很简单——转成无损 PNG 再喂给工具。
5.3 华为应用市场上架时图标被驳回
如果只是内部测试，图标只要能在桌面上正常显示就行；但一旦准备上架华为应用市场，审核就会严格很多。我遇到过被驳回的理由是“图标未使用安全区”“图标背景层带透明像素”和“前景层内容占比过小”。这三点都跟图层规范有关。适配时最好在生成器里加一个约束：生成前景图前，先把源图中央 80% 区域放大到画布的 90% 以上，同时确保背景层完全不透明。这套规则跟华为开发者文档里对素材的要求基本能对齐。
5.4 其他高频问题速查表
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| 生成文件没有出现在 ohos 目录 | 路径硬编码与工程结构不匹配 | 检查 ohos/entry 路径是否存在，建议用配置文件指定入口 |
| module.json5 引用报错 | 文件名包含大写或非法字符 | 统一改为小写与下划线 |
| 背景层与前景层重叠后观感不佳 | 前景图安全区预留不足 | 生成前景时画布放大 1.2 倍，主体居中 |
| 构建时提示 media 资源重复 | 旧文件未清理 | 生成前清空目标目录，或者按固定命名覆盖 |
| 图标在部分设备上被过度放大裁切 | 源图主体超出安全区 | 回源修图，把主体控制在中心圆内 |
| CI 脚本跑完 git 有大量无关 diff | 生成逻辑不幂等 | 输出内容加入哈希后缀或排序输出，确保不稳定时间戳不进入文件 |
5.5 关于这套适配方案，我最想说的一点
说实话，给 flutter_app_icon 做鸿蒙适配的过程中，技术难点并不在于“Dart 代码怎么写”，而在于你是否理解 OpenHarmony 的资源管理哲学：图标不是一张图片，而是一组图层的组合。只要抓住了前景、背景、安全区、尺寸档位和 module.json5 引用这五个关键点，剩下的就是不断跑脚本、看真机效果、调整参数的体力活。
经过这次改造，我团队现在发版时的图标更新动作已经收敛成一行命令：替换源图，跑打包流水线，全部端侧图标自动就位。我能明显感觉到，把“视觉资产部署”这件事交给自动化之后，不再依赖某个会切图的同事有空，也不再担心临近发版才发现某台设备图标尺寸不对。这套流程从 OpenHarmony 到 Android、iOS 完全统一，质量反而比手工切图更稳定。
如果你也在做 Flutter 多端工程，我强烈建议找时间梳理一下自己的资源生成链路，别让图标这种看起来很小的事拖慢整个发版节奏。按我在上面的方案去改，不用重构业务代码，半天时间就能落地。
