Flutter 三方库 web_ffi 的鸿蒙化适配指南

下面这个例子可以帮助你快速建立直觉：Dart 侧仍然按 FFI 的方式声明函数类型，真正执行时则由 WASM 模块完成计算。

import 'package:web_ffi/web_ffi.dart';

// 1. 定义与原生 ffi 一致的函数签名
typedef NativeAdd = Int32 Function(Int32 a, Int32 b);
typedef DartAdd = int Function(int a, int b);

Future<void> driveOhosWebFfi() async {
  // 2. 加载鸿蒙端的 Wasm 资源
  final module = await WasmModule.load('ohos_math_lib.wasm');

  // 3. 建立模拟的动态库访问入口
  final dylib = DynamicLibrary.fromModule(module);
  final addFunc = dylib.lookupFunction<NativeAdd, DartAdd>('add');

  // 4. 直接调用 WASM 导出函数
  final result = addFunc(100, 200);
  print('来自鸿蒙 WASM 的运算结果: $result');
}

这段代码的关键不在于'写法新鲜'，而在于它把原先原生侧的调用习惯原封不动地搬到了 Web 端。对于团队来说，这意味着迁移成本会低很多。

典型应用场景

浏览器内加密计算

在鸿蒙版 Web 客户端里，如果你要做国密算法、签名验签或其他敏感计算，web_ffi 很适合承接这类逻辑。算法本体仍然放在 C/C++ 或其 Wasm 版本中，Dart 只负责参数组织和结果回收。这样做的好处是性能和实现一致性都更容易兼顾。

Web 端音视频处理

像 FFmpeg 滤镜、图像处理、像素批处理这类任务，往往不适合用纯 JS 直接硬扛。借助 web_ffi，可以把原本在 Native 侧验证过的处理链路迁移到 Web 端，Dart 侧继续作为 Glue Code 负责调度与资源管理。

适配时最容易踩的两个坑

线性内存要管住

WASM 的内存是受限的，尤其是在 WebView 或浏览器环境里，内存峰值一旦失控，页面崩掉往往没有太多预警。实际使用 web_ffi 时，大块内存分配要尽量受控，malloc 分配之后也一定要在合适的时机 free()。

如果是处理图像、音频或大数组，建议把生命周期想清楚：谁申请、谁释放、何时释放，最好在调用链里就定下来，不要把内存管理留给'后面再说'。

不要频繁跨边界调用

Dart 到 WASM，再到 JS 绑定层，每次跨边界都会有封送开销。如果你在动画帧循环里高频率地做小粒度调用，性能通常不会理想。更稳妥的做法是先在 Dart 侧组织好缓冲区，把数据尽量批量送入 WASM，一次性完成处理，再把结果带回来。

一个更贴近实战的处理方式

像像素处理这类场景，通常不是'调一个函数就完事'，而是要把输入缓冲区、输出结果和内存释放都安排好。下面这段代码展示的思路就是：先分配空间，再写入数据，随后交给 WASM 做处理，最后释放资源。

class OhosWebImageProcessor {
  void process(Uint8List pixels) {
    // 分配 WebAssembly 侧内存
    final ptr = malloc<Uint8>(pixels.length);

    // 把 Dart 数据拷进去
    ptr.asTypedList(pixels.length).setAll(0, pixels);

    // 调用 WASM 加速函数
    ohosWasmBlurFunc(ptr, pixels.length);

    // 及时释放，避免内存泄漏
    free(ptr);
  }
}

这里真正值得注意的是内存闭环：分配、使用、释放必须完整，否则 Web 视图里的问题通常不会立刻暴露，但一旦积累到阈值，排查起来会非常麻烦。

小结

web_ffi 解决的不是'能不能在鸿蒙 Web 里调 WASM'这么单一的问题，而是尽量让原本基于 dart:ffi 的工程结构在 Web 端延续下去。对需要兼顾原生 HAP 和 Web 场景的项目来说，这种一致性非常宝贵。

如果你已经有成熟的 C/C++ 计算库，或者业务里本来就有一层 FFI 抽象，那么 web_ffi 值得认真评估。它的价值不在于替代全部 Web 逻辑，而在于把那些真正适合底层加速的部分，稳稳接到鸿蒙 Web 端上。