跳转到正文

在浏览器里批量解码 HEIC:libheif WASM 的四个坑和一个 4.5MB 的内存方案 ​

HEIC 是 iPhone 默认的照片格式,但浏览器厂商出于专利原因普遍不支持。想让用户把 iPhone 照片拖进网页就转成 JPG,就得自己在浏览器里解码 HEIC。

能用的方案只有一个:libheif 编译成 WASM,也就是 npm 上的 libheif-js。它确实能用,但文档几乎为零,实际接进去踩了四个坑。

先说结论:一个 decoder 实例复用到底,每张图解码完立刻 free(),100 张图只增加 4.5MB 内存。如果每张图 new 一个 decoder,100 张图的峰值是 195MB。

坑一:默认导出不是对象,是工厂函数 ​

大部分 WASM 库的用法是 import libheif from 'libheif-js' 然后直接用。libheif-js 不是。

js
// ❌ 得到的 HeifDecoder 是 undefined
import libheif from 'libheif-js/wasm-bundle';
const decoder = new libheif.HeifDecoder();  // TypeError

// ✅ 要先调用一次拿到实例
const mod = await import('libheif-js/wasm-bundle');
const libheif = typeof mod.default === 'function' ? await mod.default() : mod.default;
const decoder = new libheif.HeifDecoder();

await mod.default() 这个调用是初始化 WASM 运行时。它返回 Promise,不 await 就会拿到一个空壳。

如果是 Vite / esbuild 打包,还需要把 libheif 的 bundle 作为 external 保留,用动态 import(url) 加载,否则打包器会试图解析它的内部路径然后失败。

坑二:display() 是异步回调,不是返回值 ​

其他解码库一般是 const imageData = decoder.decode(buffer)。libheif 不是:

js
// ❌ 拿到的 pixels 是空的
img.display({ data: out, width: w, height: h }, () => {});
console.log(out);  // 全黑或全透明

// ✅ 必须等回调
await new Promise((resolve, reject) => {
  img.display({ data: out, width: w, height: h }, (result) => {
    if (!result) return reject(new Error('decode failed'));
    resolve();
  });
});

display() 内部用 setTimeout 把实际的像素拷贝推迟到下一轮事件循环。如果不等待回调就读 out 缓冲区,读到的是上一张图的残留数据,或者全黑。

这个坑很隐蔽:单张图测试时不一定出错,因为同步路径有时能跑完;批量处理时才稳定复现。

坑三:is_primary 会指向 150×150 的缩略图 ​

HEIC 文件内部可以有多张图:主图、缩略图、深度图等。直觉上应该用 is_primary() 挑主图:

js
const imgs = decoder.decode(buffer);
const primary = imgs.find(x => x.is_primary());

但实测有照片的 is_primary 标记指向一个 150×150 的缩略图,直接对它调 display() 会失败或者得到一张缩略图。

原因不深究(不同编码器的写出行为不一致),解决办法是按面积加权,只在 is_primary 的图足够大时才信它:

js
const imgs = decoder.decode(buffer);

const primary = imgs.find(x => x.is_primary && x.is_primary());
const largest = imgs.reduce((best, x) => {
  const ax = x.get_width() * x.get_height();
  const bx = best ? best.get_width() * best.get_height() : 0;
  return ax > bx ? x : best;
}, null);

const primPixels = primary ? primary.get_width() * primary.get_height() : 0;
const largestPixels = largest ? largest.get_width() * largest.get_height() : 0;

// 主图至少要有最大图的 25%,否则认为标记不可信,用最大的
const chosen = (primary && primPixels >= largestPixels * 0.25) ? primary : largest;

按这个规则,一批 34 张图里那张解码失败的 C039.heic 也通过了,最终 34/34 全部成功。

坑四:free() 的时机决定成败 ​

libheif 的每张子图都要手动 free(),否则 WASM 堆会一直涨。但在哪一刻 free 很关键:

js
// ❌ 先 free 再 resolve —— 成功数从 34 掉到 33
img.display({...}, (result) => {
  freeAll(imgs);
  resolve(result);      // 此时缓冲区可能已被回收
});

// ✅ 先 resolve 再 free
img.display({...}, (result) => {
  resolve({ data: out, width: w, height: h });
  freeAll(imgs);        // 在 resolve 之后
});

看起来反直觉,但 resolve 只是把 Promise 标记为完成,后续的 .then() 是微任务。只要 free 放在 resolve 之后,调用方拿到的 out 缓冲区仍然是有效的。

内存:从 195MB 到 4.5MB ​

前三坑解决后功能通了,但批量处理 100 张图时浏览器直接 OOM。原因是每个文件都 new 一个 decoder:

js
// ❌ 195MB(100 张)
for (const file of files) {
  const decoder = new libheif.HeifDecoder();   // 每次都初始化 WASM
  const imgs = decoder.decode(await file.arrayBuffer());
  ...
}

HeifDecoder 的构造会实例化一套 WASM 上下文,几十上百次累积起来非常可观。改成单个实例复用 + 输出缓冲区复用:

js
// ✅ 4.5MB(100 张)
const decoder = new libheif.HeifDecoder();      // 全局只建一次
let out = null;                                  // 输出缓冲区也复用

for (const file of files) {
  const imgs = decoder.decode(new Uint8Array(await file.arrayBuffer()));

  // 按坑三的规则挑图
  const img = pickImage(imgs);
  const w = img.get_width(), h = img.get_height();
  const need = w * h * 4;

  // 缓冲区够大就复用,只在需要更大时才重新分配
  if (!out || out.length < need) out = new Uint8ClampedArray(need);

  await new Promise((resolve, reject) => {
    img.display({ data: out, width: w, height: h }, (result) => {
      if (!result) { freeAll(imgs); return reject(new Error('decode failed')); }
      resolve();
      freeAll(imgs);
    });
  });

  // out 里的像素已经是 RGBA,直接画到 canvas 导出 JPG/PNG
  ctx.putImageData(new ImageData(new Uint8ClampedArray(out.buffer, 0, need), w, h), 0, 0);
  const blob = await canvas.convertToBlob({ type: 'image/jpeg', quality: 0.92 });
  results.push(blob);
}

关键就三点:

  1. decoder 全局一个,不要 per-file
  2. 输出缓冲区复用,只在尺寸变大时才重新分配
  3. 每张图 free 掉 imgs,且放在 resolve 之后

100 张实测下来峰值内存增量约 4.5MB,处理过程中浏览器完全流畅。

顺带一提:Live Photo ​

Live Photo 是一对文件:.heic(静图)+ .mov(约 3 秒视频)。要做成 GIF 或 MP4,得先按文件名配对,再把 MOV 拆帧。

MOV 解码不能靠 libheif,要用 <video> + canvas 抽帧:

js
const video = document.createElement('video');
video.src = URL.createObjectURL(movFile);
video.muted = true;
await new Promise(r => video.addEventListener('loadedmetadata', r, { once: true }));

这里有个 Firefox 的坑:iPhone 的 Live Photo 视频通常是 HEVC 编码,Firefox 不解 HEVC。但 Firefox 的行为很狡猾——它会先触发 loadedmetadata 让你以为成功了,然后再触发 error,video.error.code === 3。

所以只在 loadedmetadata 后判断是不够的,要三重校验:metadata 成功 → 能 seek → 能 drawImage 且画出来不是全透明。三步都过才算真的能解码。

小结 ​

坑现象解法
默认导出是工厂HeifDecoder is undefinedawait mod.default()
display 是回调输出全黑包成 Promise 等回调
is_primary 不可信解出 150px 缩略图面积加权,≥25% 最大图才采信
free 时机偶发解码失败free 放在 resolve 之后
内存爆炸100 张 195MB → OOMdecoder + 输出缓冲区双重复用

这套东西最后做成了一个纯本地运行的转换器,文件不上传,全在浏览器里解码:

参考 ​

  • libheif — 底层 C++ 库
  • libheif-js — WASM 构建,本文版本 1.23.5
  • gifenc — 纯 JS 的 GIF 编码器,不需要 Worker 脚本,对 MV3 CSP 友好

站内相关 ​

把知道的留下,把不懂的写下来。