★ FEATURED ARTICLE 1. 为什么要把图片占位这种小事做到极致1.1 图片加载焦虑是怎么来的做 Flutter 应用的这两年我发现自己大半的优化精力都耗在图片上。列表页快速滑动网络图还在路上用户盯着空白卡片、灰色占位块手一滑又触发一次重绘主岛上堆满解码任务掉帧成了家常便饭。尤其鸿蒙端早期 Flutter 适配不成熟时图片加载链路比 Android 更长空白感更明显。所谓图片加载焦虑本质是网络 IO 与 UI 渲染的速度差导致的体验撕裂。你没法让弱网变快但能让用户感觉快。这里有个成熟思路先渲染一张体积极小、和原图色彩轮廓一致的模糊占位图等真图解码完再平滑替换。用户看到的不再是白屏而是图片正在慢慢清晰的视觉过渡。这就是 blurhash 这类技术存在的意义。1.2 blurhash 的原理一张图压缩成一串字符blurhash 的核心逻辑不复杂把一张图片的像素信息经过 DCT 变换后提取低频分量量化编码成一串 20~30 字符左右的短字符串。这串字符串可以放在后端接口里和图片 URL 一起下发客户端拿到后只需解码这串字符就能在几十毫秒内生成一张宽高很小的模糊预览图再拉伸铺满原图区域。听起来像缩略图但它比缩略图更省缩略图还要传字节流而 blurhash 只是一个字符串。解码成本极低没有网络请求纯本地计算。也正因如此它非常适合做首屏占位——在真正的 Image 加载出来之前先用模糊色块填充画面。常用的场景包括聊天消息里的图片预览、电商商品列表的卡片占位、瀑布流图片的加载过渡。配合 CachedNetworkImage 这类缓存库做 fade 切换视觉上非常顺滑。1.3 为什么偏偏选 fast_blurhash 这个 Rust 版本Flutter 生态里 blurhash 的纯 Dart 实现不少但我最终选择 fast_blurhash看中的是它的底层实现解码计算是用 Rust 写的通过 dart:ffi 暴露给 Dart 层调用而不是用 Dart 逐像素循环计算。这里有个关键认知blurhash 解码虽然不算重但也不是纯字符串解析那么简单它涉及离散余弦变换、反变换、像素值 clamp、色彩空间处理如果每次都在 Dart isolate 里做首帧延迟和 CPU 占用都会明显偏高。Rust 版本的优势在于代码编译成机器码没有 Dart VM 解释开销矩阵运算走的是经过优化的数值逻辑加上内存布局是连续数组性能比纯 Dart 实现快一个量级。我在 Android 上实测过同样一张 32x32 的预览图纯 Dart 解码大概需要 8~12msfast_blurhash 的 FFI 调用则稳定在 1ms 以内。乍一看差距不大但图片列表一多、滚动一快积少成多体验差异就出来了。所以当你把这个库向鸿蒙迁移时核心问题不是怎么用而是怎么让里面的 Rust 动态库在鸿蒙系统上跑起来。这正是本文要解决的。2. 鸿蒙适配前必须搞清楚的三个问题2.1 Flutter 鸿蒙版的插件承载方式鸿蒙HarmonyOS NEXT / OpenHarmony上跑 Flutter目前社区和厂商提供的方案本质上还是把 Flutter 引擎编译成鸿蒙的原生动态库然后在 ArkUI 工程里通过 Ability 来承载 Flutter 页面。老牌的 FunctionDriven 之类我们不用纠结你只需要知道Flutter 鸿蒙版已经能跑而且插件系统也在逐步对齐。插件在鸿蒙上的承载方式和 Android 类似会在插件工程里多出一个 ohos 目录。pubspec.yaml 中的 flutter 插件声明会被 DevEco 构建工具识别把 so 和注册文件打进去。区别在于鸿蒙的插件代理方法不是 Android 的 MethodChannel 原生端那一套而是通过 OHOS 侧的 PlatformChannel 注册机制EventChannel、MethodChannel、BasicMessageChannel 在鸿蒙 Flutter 引擎里都有对应实现。这些通信机制对 fast_blurhash 来说其实是多余的因为 fast_blurhash 不需要原生 UI也不需要调用系统 API它只需要一个动态库和一个 FFI 绑定。也就是说它属于最友好的一类插件适配鸿蒙的核心是编译产物而不是桥接逻辑。2.2 dart:ffi 在鸿蒙能跑但 so 得自己给dart:ffi 是 Dart 语言内置的机制和 Flutter 引擎绑定方式无关。只要 Flutter 引擎在鸿蒙上能正常执行 Dart AOT/JIT 代码dart:ffi 就能用。这一点我在适配过程中实测确认过DynamicLibrary.open 在鸿蒙 Flutter 上工作正常符号查找、指针传参、回调函数都能走通。问题的关键在so 从哪来。fast_blurhash 官方仓库预编译了 Android、iOS 等平台的动态库但不会预编译鸿蒙版本。所以我们要做的就是用 Rust 工具链交叉编译出 .so然后放进应用包里保证运行时能被加载。听起来简单实际动手时会踩到不少架构、链接、打包的坑。另外要明确一个概念鸿蒙用的 so 是 ELF 格式和 Linux 类似但系统库接口、C 标准库和 Android 不是一套。直接拿 Android 的 arm64-v8a so 放到鸿蒙上跑大概率会闪退报找不到符号或 RELRO 校验失败。原因在于鸿蒙的 libc、libc 实现和 Android Bionic 不一样动态库依赖的符号版本也不同。2.3 环境准备Flutter OHOS / DevEco / Rust 工具链动手前先把环境理清楚少走弯路。Flutter 本身需要切到支持鸿蒙的分支一般是 flutter_flutter 的 ohos 分支或者厂商提供的 Flutter SDK。不同版本对应的 Flutter 引擎 API 有差异建议先用官方 release 版本不要拿 beta 分支踩坑。DevEco Studio 装好并配置好鸿蒙 SDK 和 NDK。鸿蒙 NDK 里最关键的是 llvm 工具链和 sysroot路径一般在 SDK 目录下的 native 子目录里比如$OHOS_SDK/native/llvm和$OHOS_SDK/native/sysroot。交叉编译 Rust 时链接器和系统库都从这里取。Rust 工具链建议用 rustup 管理版本不要太老因为 aarch64-unknown-linux-ohos 这类 target 是较新的 Rust 版本才稳定支持的。装好后先检查一下 rustup target list 里能不能看到 ohos 相关的 target看不到就先更新 rustup 和工具链。我常用的环境组合Flutter ohos 3.22 分支、DevEco Studio 5.x、Rust 1.75、OHOS SDK 12。这套组合在真机上验证比较稳。3. 实战Rust 交叉编译出鸿蒙动态库3.1 拿到 native 工程并确认 crate 结构fast_blurhash 的仓库里native 部分是一个标准的 Rust crate。你不需要完全看懂它但得确认三件事是不是 cdylib生成动态库的 crate-type、FFI 导出函数叫什么、依赖了哪些第三方 crate。确认 crate-type 很简单看 native/Cargo.toml 里的 [lib] 段通常长这样[lib] crate-type [cdylib]如果不放心可以直接在仓库根目录搜#\[no_mangle\]所有导出给 Dart 调用的函数都会带这个标记。导出的函数名就是我们后面在 Dart 里 lookup 的符号名。依赖方面要注意依赖树里是否包含需要 C 编译器的 crate比如 ring、libsqlite3-sys 这类。fast_blurhash 的依赖相对干净主要是基础数学和图像处理 crate纯 Rust 实现交叉编译时不需要额外处理 C 依赖。如果你们项目里要适配其他 Rust 库这一步要重点检查。3.2 注册 ohos 编译目标Rust 官方已经内置了鸿蒙的 target不需要像早期那样自定义 target.json。用 rustup 添加即可rustup target add aarch64-unknown-linux-ohos armv7-unknown-linux-ohos x86_64-unknown-linux-ohos三个 target 分别对应鸿蒙的 arm64-v8a、armeabi-v7a、x86_64 架构。真机主要用 aarch64 那个x86_64 主要用于鸿蒙模拟器。添加完之后用rustup target list --installed确认一下。如果这一步报错 target not found大概率是 Rust 工具链版本太旧先rustup update stable再试。有人会问只适配真机的话是不是只用加 aarch64 就够了我的建议是三个都加上因为模拟器调试和以后平板、折叠屏都是 arm64但开发期总有人想用模拟器验证有 x86_64 的 so 会方便很多。多架构可以一次性编出来成本并不高。3.3 配置 NDK 链接器和系统库Rust 交叉编译本身不愁编译器rustc 会生成目标平台的机器码。但链接器需要一个能识别鸿蒙目标文件格式、能链接鸿蒙系统库的 clang这个 clang 就来自 OHOS NDK。我习惯用环境变量方式配置不写进 Cargo 全局配置避免影响其他项目export OHOS_NDK/path/to/ohos-sdk/native export PATH$OHOS_NDK/llvm/bin:$PATH export CC_aarch64_unknown_linux_ohosclang --targetaarch64-linux-ohos --sysroot$OHOS_NDK/sysroot export AR_aarch64_unknown_linux_ohosllvm-ar export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_OHOS_LINKERclang --targetaarch64-linux-ohos --sysroot$OHOS_NDK/sysroot注意几点--targetaarch64-linux-ohos是 clang 的三元组告诉 clang 按鸿蒙 ABI 生成代码这是和普通 Linux 交叉编译的关键区别。sysroot 必须指向 OHOS NDK 的 sysroot里面包含鸿蒙的 libc 头文件、crt 文件、链接脚本。链接器要用 clang不要直接配成 gcc 或 ld因为 clang 会帮忙处理 sysroot 和隐式库路径。如果项目里有 build.rs还需要设置CARGO_TARGET_AARCH64_UNKNOWN_LINUX_OHOS_CC环境变量让 build.rs 里调用的 C 编译器也是同一个 clang。我建议直接写一个脚本把环境变量和 cargo build 命令放一起方便重跑。也可以考虑在项目根目录放.cargo/config.toml把以上配置固化下来。好处是团队其他人 clone 后不需要猜环境变量坏处是配置里如果写死本机路径容易造成冲突。我个人倾向于在 CI 脚本或适配脚本里用环境变量动态注入。3.4 多架构一次性构建与产物校验环境变量配好后执行构建cd native cargo build --release --target aarch64-unknown-linux-ohos cargo build --release --target x86_64-unknown-linux-ohos产物分别在target/aarch64-unknown-linux-ohos/release/libfast_blurhash.sotarget/x86_64-unknown-linux-ohos/release/libfast_blurhash.so构建完成后强烈建议做两个校验动作。先看架构file target/aarch64-unknown-linux-ohos/release/libfast_blurhash.so正常输出会包含ELF 64-bit LSB shared object, ARM aarch64字样。再检查所需依赖系统库llvm-readelf -d libfast_blurhash.so | grep NEEDED鸿蒙的 so 应该只依赖libc.so、libdl.so、libm.so这类基础库。如果出现libstdc.so或者 Android 的liblog.so说明链接参数有问题装到鸿蒙上大概率加载失败。我遇到过最典型的问题是链接器把 Rust 标准库的某些符号解析到了 glibc 版本上生成的 so 在鸿蒙 load 时报cannot locate symbol。解决方法是确认 clang 的 target 三元组和 sysroot 都指向 OHOS重新 clean 后再编。4. Dart 侧 FFI 绑定的鸿蒙化改造4.1 绑定文件的平台分支拿到鸿蒙可用的 so 后回到 Flutter 包侧。fast_blurhash 的 Dart 端代码里动态库加载和 FFI 函数查找一般集中在一个文件。要做的改动是给它加一个平台分支让它在鸿蒙上也能找到libfast_blurhash.so。常见写法是这样import dart:ffi; import dart:io show Platform; DynamicLibrary _openBlurHashLibrary() { if (Platform.isAndroid || Platform.isIOS || Platform.isOHOS) { return DynamicLibrary.open(libfast_blurhash.so); } // Linux/macOS 直接打开系统路径, 这里省略 return DynamicLibrary.open(libfast_blurhash.so); }注意Dart SDK 里判断鸿蒙平台的方式取决于你用的 Flutter 分支。有的分支里 Platform.isOHOS 还不存在需要自己通过Platform.operatingSystem ohos判断有的已经内置了。我在适配时选择先判断Platform.isOHOS再回退到字符串比较兼容性更好。代码里还有一个坑如果直接用DynamicLibrary.process()或全路径打开在鸿蒙上的表现和 Android 不同。鸿蒙的 so 查找路径基于应用沙箱建议不要自己拼接绝对路径直接传文件名让系统按默认规则搜索。4.2 从解码到 UI.Image 的完整链路FFI 函数绑定只是第一步真正要交付的是一张可以给 Flutter 渲染的图片。完整链路是blurhash 字符串 - Rust 解码得到 RGBA 字节数组 - 包装成 ui.Image - 通过 Image 展示或作为占位符。Rust 侧解码函数的 FFI 定义大致如下示意代码具体以仓库导出符号为准#[no_mangle] pub extern C fn fast_blurhash_decode( hash: *const c_char, width: u32, height: u32, punch: f32, out: *mut u8, ) - i32Dart 侧对应声明typedef DecodeNative Int32 Function( PointerUtf8 hash, Uint32 width, Uint32 height, Float punch, PointerUint8 out, ); final int Function( PointerUtf8, int, int, double, PointerUint8, ) _decode _lib .lookupFunctionDecodeNative, DecodeNative(fast_blurhash_decode);注意 dart:ffi 的映射规则Rust 的 u32 对应Uint32f32 对应Float返回值i32对应Int32。指针参数用PointerT。调用前要给输出缓冲区分配width * height * 4字节因为 RGBA8888 每像素 4 字节。拿到字节数组后转成 ui.Image 可以这样final Completerui.Image completer Completer(); ui.decodeImageFromPixels( rgbaBytes, width, height, ui.PixelFormat.rgba8888, completer.complete, ); final ui.Image image await completer.future;然后你用RawImage或Image(image: image)渲染都行。为了和现有图片缓存库配合我通常把这个 decode 流程封装成一个Futureui.Image decodeBlurHash(String hash, int w, int h)函数方便在 frameBuilder 里异步调用。4.3 怎么和现有图片缓存库一起用fast_blurhash 单拿出来只是能力要解决图片加载焦虑必须嵌入实际加载流程。我推荐的做法是和 cached_network_image 或自己封装的图片组件联动。一个简单的占位替换逻辑Image.network( url, frameBuilder: (context, child, frame, wasSync) { if (frame ! null) { return child; } return FutureBuilderui.Image( future: decodeBlurHash(hash, width, height), builder: (context, snap) { if (snap.hasData) { return RawImage(image: snap.data, fit: BoxFit.cover); } return ColoredBox(color: placeholderColor); }, ); }, )这样真图加载完成前画面先展示模糊占位真图解码完成后Flutter 会在下一帧用 child 替换占位视觉上是模糊 - 清晰的渐变不突兀。有些同学喜欢用 AnimatedSwitcher 做交叉淡入淡出我实测在鸿蒙上效果也不错但要注意 frameBuilder 里切换 child 时避免重建整个组件树控制好 duration300ms 左右手感最好太长会显得拖沓。5. 性能优化别让一个轻量库卡住 UI5.1 解码放 isolate 的必要性判断很多人一听说 FFI 调用就默认它不会卡 UI这是个误区。dart:ffi 的调用本身是同步的RNN 解码期间当前 isolate 的事件循环会被阻塞。单个 blurhash 解码只有 1ms 左右阻塞感不明显但如果列表页一屏有十几个占位图依次解码累计起来就是十几毫秒在低端鸿蒙设备上会造成肉眼可见的丢帧。我的判断标准很简单单次解码不超过 2ms、同一帧内解码数量不超过 3 个可以放在主 isolate否则就用 compute 或自定义 decode isolate 去做。由于 fast_blurhash 的 Rust 解码函数是纯计算、无状态、无回调把一个 32x32 的 RGBA 字节数组通过 isolate 传回主 isolate 的成本很低约 4KB完全值得用 isolate 隔离。我用的是 Flutter 的 compute 顶层函数final rgba await compute(decodeBlurHashPure, DecodeRequest(hash, w, h));注意传入 compute 的参数必须是可拷贝的简单数据不能直接传 Pointer所以要在函数内部完成 FFI 调用和字节数组拷贝返回普通 Uint8List。5.2 内存与对象的复用解码占位图的尺寸一般不大常见的是 32x32 或 64x64。单个 RGBA 数组峰值也就 16KB 左右但对高频调用场景频繁分配和 GC 仍然会带来压力。我建议做一层结果缓存同一个 hash 和尺寸组合解码结果直接放进 LRU Map避免重复计算。final MapString, ui.Image _cache {}; String _key(String hash, int w, int h) $hash-$w-$h; Futureui.Image decodeCached(String hash, int w, int h) async { final key _key(hash, w, h); final hit _cache[key]; if (hit ! null) return hit; final image await decodeBlurHash(hash, w, h); if (_cache.length 200) { _cache.remove(_cache.keys.first); } _cache[key] image; return image; }这里有个细节ui.Image 是原生资源不能无限缓存一定要设置上限否则内存会持续上涨。我在真机上观察200 个 32x32 的占位图缓存占用大约 800KB 原生内存属于可接受范围。另外同一个 hash 解码出的像素数据可以直接复用到多个 Image 渲染前提是你通过 RawImage 渲染同一个 ui.Image 实例。这比各自解码再生成图片要省大量内存。5.3 预热首屏前把占位图准备出来图片加载焦虑最严重的场景是首屏。用户刚进入页面网络请求还没回来这时所有占位图才开始解码即使单次 1ms一屏十几个也会造成短暂卡顿。我的做法是在页面 initState 阶段提前把首屏可见区域的 blurhash 解码任务发出去不等加载到 Image 组件时才触发override void initState() { super.initState(); _preloadPlaceholders(); } Futurevoid _preloadPlaceholders() async { final requests visibleItems.map((e) decodeCached(e.hash, 32, 32)); await Future.wait(requests); }这样用户真正看到图片列表时占位图已经在缓存里frameBuilder 取到的是瞬时数据占位替换不会产生闪烁或白屏。注意预热时不要一下并发太多建议用 Future.wait 同时跑 5~6 个即可避免瞬时打爆主岛或框架线程。6. 打包与加载的坑一个个踩给你看6.1 常见问题速查表适配过程中我在鸿蒙真机和模拟器上遇到了不少问题整理成速查表大家可以直接对照排查。现象可能原因排查与解决启动时崩溃日志出现 dlopen failed 或 cannot locate symbolso 与鸿蒙系统库不兼容或链接了 glibc 符号用 llvm-readelf 查 NEEDED 和 UND symbol确认 sysroot 指向 OHOS NDK找不到 libfast_blurhash.soso 没有打包进应用 lib 目录检查 ohos/libs/arm64-v8a 或 entry libs 路径重启 DevEco 缓存x86_64 模拟器上报 exec format error把 arm64 的 so 装到了 x86_64 环境确认 target 架构模拟器单独打 x86_64 so调用 FFI 后 Dart 层闪退但无 Dart 异常Rust 侧 panic 或非法内存访问在 Rust 侧加 panic hook 输出日志检查指针是否为空输出缓冲区大小是否够热重载后 so 未更新DevEco 对 so 变更感知不敏感clean 工程再构建不要依赖增量热重载列表滚动时偶发帧抖动解码未隔离且并发多把解码移入 compute限制并发数复用 ui.Image6.2 我在鸿蒙真机上实测的加载表现我在一台 arm64 鸿蒙真机上做了对比测试。同一批 20 张商品图分别用三种方式加载纯白占位真图到了直接替换纯 Dart blurhash 解码做占位fast_blurhash FFI 解码做占位结果很直观纯白占位方案最省事但视觉跳跃感最重纯 Dart 实现从解码到渲染首屏占位图大约耗时 160ms能感到轻微迟滞FFI 方案几乎瞬时首屏 20 张占位图在 20ms 内全部就绪真图淡入时用户基本无感。发热和内存方面FFI 方案由于解码计算集中在原生层CPU 占用比纯 Dart 低列表快速滑动时没有出现明显掉帧。整个适配改动量不大核心就是一次 Rust 交叉编译和一段平台分支代码但它带来的体验提升是质变的。再提醒一句不同版本的 Flutter 鸿蒙分支对 so 的打包路径和加载方式可能有细微差异。如果你照着本文操作建议先用最小 Demo 验证DynamicLibrary.open能通再接入业务页面这样能快速隔离问题是出在编译还是出在集成链路。
阅读完成 · 觉得有帮助？
