Flutter鸿蒙应用瘦身：asset_opt资源优化全流程实践

直接说结论：Flutter 应用想要在鸿蒙（HarmonyOS）生态里站住脚，资源体积这道坎绕不过去。我之前把 iOS/Android 双端都在用的asset_opt资源优化库往鸿蒙构建链路里硬搬，一开始完全是被现实逼的——HAP 打出来 80 多 MB，DevEco Studio 的资源压缩只在 stage 模型的 media 目录上生效，而这堆体积的大头，全藏在 Flutter 打包产物flutter_assets里，hvigor 根本不碰它。折腾了两周，总算把这套“资产优化自动化工作流”跑通了，现在 HAP 稳定在 30 MB 上下，构建流水线每天自动出包，这篇就把适配过程、核心改造点和踩坑记录全交代清楚。

1. 先搞清楚 asset_opt 到底是做什么的，鸿蒙化难点在哪

1.1 资源“三重泄漏”：HAP 体积是怎么膨胀起来的

很多团队做鸿蒙适配时，默认把 Flutter 工程当成一个黑盒，flutter build出来什么就塞什么。这么搞，体积失控几乎是必然的。我拆包检查后发现，资源浪费主要来自三个层面。

第一层是重复的多分辨率图片。设计同事交付一套 3x 图，Android 上各个 drawable 目录各放一份，Flutter 的assets/images里也塞一份，鸿蒙的media里又拷一份，同一张启动图在 HAP 里以三种格式出现三次。第二层是未引用资源，一个项目迭代两年后，assets目录里大量 PNG、JSON、字体文件早就没人用了，但 Flutter 的打包器不管这些，全量打进去。第三层是打包粒度太粗，所有--split-debug-info、--obfuscate能压缩的只有 dart 代码，图片本身占的体积一分不减，更别说那些构建中间产物和符号文件残留在 asset 目录里的情况。

asset_opt在 Android/iOS 上的定位就是解决这三层问题：扫描真实引用、压缩图片、剔除死资源、字体子集化。它本质上是一个“构建后置处理器”，在 Flutter 产物落地之后、原生工程打包之前插入一道工序。理解了这个定位，鸿蒙适配的重点就清楚了——不是重写压缩算法，而是让这个后置处理器能正确识别鸿蒙工程的资源布局，并且接入 hvigor 的构建生命周期。

1.2 鸿蒙构建链路和 Android 的根本差异

Android 上 asset_opt 走的是 Gradle transform 或自定义 task，在packageDebugAssets之后执行，调用方是 Java/Kotlin，能直接操作build/intermediates/assets。鸿蒙这边完全不是一回事。

鸿蒙的构建核心是 hvigor，它负责把entry模块、har包、Flutter 产物统一编排。Flutter 产物的资源会被塞到 HAP 的resources/rawfile/flutter_assets/目录下，这个目录是纯透传的，hvigor 不会对内部文件做任何重命名、压缩或去重。更麻烦的是，鸿蒙侧的原始资源走的是$rawfile引用和$media系统资源管线，Flutter 侧的资源引用靠的却是 Dart 代码里的字符串字面量，比如Image.asset('images/logo.png')。两边各有一套资源语义，asset_opt 如果只盯着 Flutter 的asset_manifest.json干活，就会漏掉原生侧对 Flutter 资源的直接引用，反过来也会误删原生还在用的图片。

所以说，鸿蒙化的第一件事，是让 asset_opt 脱离对 Flutter 工具链的路径依赖，改为直接解析鸿蒙工程结构，搞出一份“鸿蒙视角”的资源引用图谱。这个改造做完，后续所有优化动作才谈得上准确。

2. 鸿蒙适配核心设计：资源引用图谱 + 安全压缩管线

2.1 资源引用图谱：怎么让工具“看见”鸿蒙工程里的每一张图

我在适配时给 asset_opt 加了一个HarmonyResourceScanner，它的职责就是同时扫描三个来源，汇总出一份全量引用白名单。

第一个来源是 Dart 代码层，正则扫描lib/目录下所有.dart文件里的字符串，匹配Image.asset、AssetImage、rootBundle.load、NetworkImage以外的 asset 调用，提取资源路径。这里有个容易踩的坑：代码里经常出现动态拼接路径，比如'images/${categoryId}/banner.png'，光靠正则只能匹配到前面的目录前缀，后面的具体文件会漏掉。我的处理方式是，动态目录一律整目录保留，静态文件才做精确匹配，宁可多留，不可误删。

第二个来源是pubspec.yaml的assets段和flutter_assets的实际目录树。这个必须直接读文件系统，只读 manifest 不够，因为 Flutter 的AssetManifest.bin是序列化后的非人类可读格式，解析成本高且不稳定。直接遍历build/flutter_assets目录，把文件列表拉出来跟扫描结果对照，比解析二进制 manifest 简单可靠得多。

第三个来源是原生侧，也就是entry/src/main/resources下的rawfile目录，以及module.json5、main_pages.json里引用的资源。鸿蒙应用经常需要用原生 WebView 加载 Flutter 工程里的本地 HTML，或者用原生组件访问 Flutter 拷贝进去的字体文件。如果 asset_opt 只扫 Dart 层，这些原生引用会变成“孤儿引用”，一旦被清理就是线上白屏事故。所以扫描器必须同时检查.ets、.ts、module.json5和rawfile目录里的$rawfile(...)写法，把这些也标记为保留。

2.2 压缩管线为什么要做“三级降级”

鸿蒙适配里最让人头疼的，不是压缩算法本身，而是运行环境限制。Android 上我可以直接调用 pngquant、oxipng 这些原生二进制子进程，但鸿蒙生态里不能假设构建机上一定装得了这套工具链，而且很多团队的鸿蒙流水线跑在 DevEco Studio 自带的 Node 环境里，没有特权去启外部进程。

所以我把压缩管线改成三级降级策略。第一级是外部工具加速，如果环境变量里配了ASSET_OPT_PNGQUANT_PATH，就优先调用外部 pngquant 进程，速度最快、压缩比最大。第二级是内置纯 Dart 压缩器，用image包做无损/有损重编码，速度慢一些但在任何机器上都能跑。第三级是跳过压缩，只做去重和剔除，即便没有任何编码库可用，asset_opt 也能工作，只是不吃图片压缩这部分的红利。

这个降级设计非常关键。我见过不少资源优化工具，功能是强，但拿到鸿蒙构建机上直接就挂了，因为它的依赖里有太多平台相关的东西。asset_opt 鸿蒙版保证最小化运行依赖，核心逻辑全部用纯 Dart 实现，唯一的构建环境要求就是能跑dart命令，这样就压住了集成时的意外变量。

2.3 图片压缩格式选择：WebP 不是万能药

图片压缩里有个经典选项是把 PNG 批量转 WebP。Android 上我确实这么干，收益巨大。鸿蒙上就要谨慎了。

鸿蒙原生组件的 ImageKit 从 API 8 开始就支持 WebP 解码，问题出在 Flutter 引擎侧。如果你的 Flutter 应用还运行在较老的 harmony 引擎版本上，部分 WebP 特性（尤其是带 alpha 通道的 WebP 动图）解码会有兼容性崩坏，表现是图片直接空白或者色彩通道错乱。我实测下来的稳妥做法是：大尺寸 PNG 转有损 WebP，图标和小尺寸 UI 图保留 PNG 但走无损压缩。前者体积下降明显，后者虽然优化幅度小，但胜在不会出现“小图标突然糊了”这种难以排查的回归问题。

另外要特别注意 GIF 和 WebP 动图。asset_opt 默认对动图只做原样拷贝，不做任何重编码，因为动图压缩牵扯到帧间优化和调色板量化，收益有限、风险极高。我见过有人图省事把动图转成 WebP 后，整个动画掉帧严重，最后还得回滚。优化不是压缩率越大越好，而是“在可接受风险内压缩”。

3. 实操接入：把 asset_opt 挂进 hvigor 构建链路

3.1 适配第一步：工程结构的摸底清单

动手改造之前，我建议先按下面这份清单把工程过一遍，避免改到一半发现某个目录藏了重要资源。

# 在 ohos 工程根目录执行 tree -L 3 -d ohos/entry/src/main/resources find ohos -name "*.har" -o -name "*.hsp" | head -20 du -sh ohos/entry/build/flutter_assets 2>/dev/null

重点确认三件事：一是flutter_assets是直接合入entry模块，还是作为单独的 har 包接入；二是resources/rawfile下除了 flutter 产物之外，有没有业务自己的 HTML/JS/字体；三是module.json5里assets段写了多少资源目录。这三件事决定了 asset_opt 的扫描边界和清理白名单。

顺带提一个容易被忽略的点：很多鸿蒙工程里同时存在entry和feature两个模块，Flutter 产物通常只在主模块里，但两个模块的 rawfile 可能互相引用。我一开始只扫了entry，结果 feature 模块加载原始 HTML 时直接 404，排查半天才发现是扫描范围没覆盖到。所以配置里的scanModules参数一定要显式写全，不能偷懒用默认值。

3.2 用 hvigor 插件封装 asset_opt 任务

hvigor 提供了自定义插件的机制，我选择在 hvigorfile.ts 里动态注册一个AssetOptimizePlugin，挂在assembleHap的的构建节点前执行。关键代码如下：

// hvigorfile.ts import { hvigor } from '@ohos/hvigor'; import { AssetOptHvigorPlugin } from '@ohos/asset-opt/hvigor'; export default { system: hvigor.defConfig({ plugins: [ new AssetOptHvigorPlugin({ // 只处理 release 构建，debug 跳过以保留最快迭代速度 enabled: hvigor.isRelease(), // 资源白名单，凡是匹配到的一律不清除 keep: [ 'rawfile/README.md', 'rawfile/flutter_assets/**/license/**', 'rawfile/flutter_assets/assets/fonts/**' ], // 压缩参数：大于 24KB 的图片才参与压缩 image: { minSize: 24 * 1024, quality: 80, webpThreshold: 128 * 1024 } }) ] }) };

插件内部要处理两个关键时刻：一个是在 Flutter 产物复制进rawfile之前，直接对build/flutter_assets做优化，减少后续拷贝的数据量；另一个是在 hvigor 打包前把优化结果同步到模块资源目录。这里有个先后顺序的坑——如果等到 hvigor 已经执行了资源合并再动手，文件路径和你预期的是不一样的，而且并发冲突很难调试。

为了不给构建主链路添乱，我把优化任务做成幂等操作：每次运行前先删除上一次生成的临时目录，再重新生成优化后的资源包。这样就算某个环节失败，也不会把脏数据留在 HAP 里。

3.3 增量缓存设计：别让热更新变成全量重来

日常迭代最烦的就是改一行业务代码，结果每次构建都重新压缩一遍几百张图。asset_opt 鸿蒙版加了一层基于内容哈希的缓存，原理是把资源的sha256、压缩参数、压缩器版本组合成一个cacheKey，命中缓存就直接从本地增量目录复制结果。

缓存目录我放在了ohos/.hvigor/asset_opt_cache/，没放系统临时目录，原因有两个：一是和工程同目录，团队 CI 上方便整个目录一起缓存；二是多个分支切换构建时，只要资源内容没变，缓存就能命中，构建速度提升非常明显。实测冷启动构建 5 分多钟，缓存命中后压到 1 分半左右，主要时间花在了 hvigor 本身的 gc 和 Native 编译上。

再说一个该避的坑：不要把缓存目录放进 git 仓库，但一定要在.gitignore里把它排除。有人图省事把缓存提交了，结果不同开发机的相对路径不一致，缓存全部失效，反而拖慢全团队。

3.4 自动化流水线：从本地命令到 CI 每日出包

本地跑通之后，我把它接进了团队的流水线。流水线里的执行顺序是：拉取代码 ->flutter pub get->flutter build bundle --release-> 执行 asset_opt -> 执行 hvigorw assembleHap -> 产物签名与归档。

这里有一个实践建议：asset_opt 的执行不要用 DevEco Studio 界面的“Build”按钮，而是单独把它封装成一个npm script或shell脚本，这样 CI 里可以灵活编排。我用的是一个极简包装：

#!/bin/bash # scripts/optimize_assets.sh set -euo pipefail FLUTTER_ASSETS="${1:-ohos/entry/build/flutter_assets}" OUTPUT_DIR="${2:-ohos/entry/build/optimized_assets}" dart run asset_opt:optimize \ --input "$FLUTTER_ASSETS" \ --output "$OUTPUT_DIR" \ --scan-root "$(pwd)/ohos" \ --manifest-cache .hvigor/asset_opt_cache

CI 里细分环境的时候，只需要在正式出包前校验--release标志和签名证书即可。我个人强烈建议Debug 包不执行任何压缩，否则每次本地热重载都在等图片压缩，开发体验会变得非常差。

4. 适配过程中的翻车现场：问题与排查实录

4.1 最大翻车：资源名被改写导致运行时报 Unable to load asset

第一次把适配版接入鸿蒙 demo 时，App 一启动就疯狂报错：“Unable to load asset: images/splash/logo.png”。排查了很久才发现，问题不是文件被删了，而是 asset_opt 在做“资源名归一化”的时候，把目录里的 PNG 重命名了。

旧版本的 asset_opt 在 Android 上有一种优化策略：把带连字符、大写、特殊符号的资源名统一改成小写下划线，因为原生资源命名不规范会导致某些 ROM 解析出错。但 Flutter 侧Image.asset引用的字符串常量是写死在 Dart 代码里的，工具侧一改文件名，代码侧引用就断了。

解决方式有两个，一是彻底关掉改名功能，二是给工具加一层“符号映射表”。我最后选择了后者：改名不是直接物理重命名，而是先生成asset_renamed_map.json，在打包时同步把 Dart 侧字符串替换掉。但这个方案复杂度上升很快，涉及const字符串替换、AssetManifest.bin重生成，投入产出比不高。写死规则：鸿蒙模式下永不启用资源改名，只在极端情况下手动指定个别文件重命名并同步修改引用。

4.2 字体子集化后中文“字体变糊、生僻字缺失”

鸿蒙生态的市场主要在中文环境，字体子集化是资源瘦身的大头，但也是最容易出安全事故的功能。

我把字体子集化的逻辑直接复用了 Android 版的经验：扫描 Dart 代码和资源文件里的文案，提取字符集合，然后用纯 Dart 的字体解析库重新生成子集字体。问题出在鸿蒙应用里有很多运行时拼接的文案，比如从服务端接口动态返回的订单状态、用户名，这些内容扫描器看不到。结果就是界面上大量文本回退到系统默认字体，设计稿的对齐和字重全乱了，还有用户反馈某些生僻字直接显示成空心方块。

这次事故之后，我的策略是提供两层兜底：第一层，允许在配置里指定一个“动态文案字符集扩展文件”，把常用汉字全量加进白名单；第二层，只对体积超过 2 MB 的字体做子集化，小字体直接原样打包。全量中文字符集大概 2 万多个字，生成的子集字体比原字体小不到哪里去，真没必要省这点空间去冒险。

4.3 增量缓存引发的“新图不更新”

缓存机制上线后的第一个 Bug 是：设计师换了一张图，打包出来的 HAP 里还是旧图。问题出在我的cacheKey只计算了资源文件内容的哈希，但漏掉了资源在构建流水线里的时间戳语义——有些构建产物（比如 WebP 重编码结果）依赖源文件的修改时间，我为了追求缓存命中率，把时间戳也排除在缓存 key 之外，结果源文件内容没变但压缩器内部参数变了，缓存命中了旧结果。

修复方式很直接：cacheKey里加上compressorVersion和一个可配置的buildFingerprint。每次 CI 构建时传入随机构建 ID，Debug 模式下强制关闭缓存，只有 Release 模式才启用。如果需要离线复现某个线上包的资源状态，构建指纹也能帮你快速定位当时用的是哪版压缩参数。

4.4 常见问题速查表

5. 收益量化、适用范围与后面还能怎么玩

5.1 实测瘦身数据和性能成本

以我负责的电商类 Flutter 应用为例（约 40 个页面、200 多张图片、5 套字体），鸿蒙适配后的资源优化效果如下：

需要说明的是，上面的压缩率是在“大量 3x PNG + 多字体”的场景下测得的，如果你的应用本身图片质量不高、素材已经压缩过，收益会缩水很多。另外，构建时长的增加主要来自图片压缩耗时，但有了缓存后，日常迭代几乎感觉不到额外的等待。

5.2 asset_opt 该在哪一步介入：本地、流水线还是发版前

根据我的经验，资源优化最好分三层推进。

最基础的一层是发版前手动跑一次。适合小团队，流程简单，只需要在打正式包前执行一次优化命令即可。缺点是容易漏跑，而且一旦忘了，就只能用一个“胖 HAP”上线。

第二层是引入 CI 自动跑。适合规模化迭代阶段，让资产优化成为流水线里不可跳过的环节。这一层要关注的是缓存策略、白名单维护、失败告警。ci 上跑脚本的回报非常稳定，因为团队不会再有人为失误。

第三层是开发阶段就开启弱优化。Debug 包只做去重、剔除和格式检查，不做重压缩，让资源问题在源代码提交阶段就暴露。这一层我在 Web 前端工程里体验过 ESLint 类似的“提交前卡点”，搬到 Flutter/鸿蒙这边，相当于让 asset_opt 校验资源合法性，比如不允许部署突然增长超过 5 MB 的图片资源，这会显著减少发版前的“资源爆炸”惊吓。

5.3 后续扩展：从资源瘦身到资源治理

asset_opt 鸿蒙化跑通以后，我已经不再把它当“压缩工具”用了，而是当“资源治理平台”的底座。

接下来的方向有三个。第一个是按需加载的资源拆分：目前的 HAP 里，所有 Flutter 资源都强制打进主包，但像新手引导图、节日大 banner、营销落地页的动画素材，完全可以把它们从 HAP 里拆出去，做成按需下载的独立资源包。asset_opt 已经有资源引用图谱了，按“冷热资源”分类只是多一步分析逻辑。

第二个是动态变体生成：鸿蒙生态正在覆盖手机、平板、折叠屏、车机多种形态，同一张 UI 图在不同屏幕密度下需要的精度不一样。asset_opt 可以对同一份源图生成多种规格的变体，运行时按设备能力加载，而不是抱着 3x 大图到处跑。这个方向配合鸿蒙的$media资源限定词，效果会很不错。

第三个是构建产物可视化报告：每次构建后自动输出一份 HTML 报告，列出资源体积占比、Top 20 大文件、新增资源清单、可继续优化的建议。团队里有人随手丢一个 8 MB 的直播封面图进 assets 时，报告里立刻就能看出来，不用等 QA 反馈“包太大装不下了”再回查。这块我正在迭代，属于“做了没人夸、不做迟早出问题”的类型。

最后分享几个经验性建议

折腾完这套鸿蒙化适配，我最大的体会是：跨端工具的鸿蒙化，真正的工作量从来不在算法层，而在构建链路的“语义对齐”。asset_opt 的图片压缩核心在 Android 上跑得好好的，代码一行不用改，鸿蒙版九成的时间都花在扫资源引用、对齐模块结构、适配 hvigor 生命周期和哄好增量缓存上。如果你手头也有一个 Flutter 三方库要往鸿蒙上搬，建议先把 Flutter 工具链和鸿蒙构建系统的资源处理差异画清楚，再动手写代码。

另外一个小建议：鸿蒙侧的自动化一定要多跑几遍“全量构建砸缓存、再增量构建”的演练。跨平台构建链路的缓存问题比单端复杂得多，Flutter 有一层缓存，hvigor 有一层缓存，asset_opt 自己还有一层缓存，三层缓存但凡有一层 key 设计漏了字段，你迟早会在凌晨两点的发版流程里被它背刺。我在踩过新图不更新的坑之后，养成了一个习惯：每次发布前清空三层缓存完整构建一遍，用这个“冷包”去验证体积和资源完整性，宁可多等那几分钟，也不要让用户下载一个资源不完整的包。