外观
在浏览器里批量解码 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);
}关键就三点:
- decoder 全局一个,不要 per-file
- 输出缓冲区复用,只在尺寸变大时才重新分配
- 每张图 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 undefined | await mod.default() |
| display 是回调 | 输出全黑 | 包成 Promise 等回调 |
| is_primary 不可信 | 解出 150px 缩略图 | 面积加权,≥25% 最大图才采信 |
| free 时机 | 偶发解码失败 | free 放在 resolve 之后 |
| 内存爆炸 | 100 张 195MB → OOM | decoder + 输出缓冲区双重复用 |
这套东西最后做成了一个纯本地运行的转换器,文件不上传,全在浏览器里解码:
- 在线使用:https://heicv.pages.dev/
- 扩展源码(只含插件外壳,处理逻辑在网站端):https://github.com/Dongmingyue-loss/heicv
参考
- libheif — 底层 C++ 库
- libheif-js — WASM 构建,本文版本 1.23.5
- gifenc — 纯 JS 的 GIF 编码器,不需要 Worker 脚本,对 MV3 CSP 友好
站内相关
- Web 开发笔记索引 — 前端与浏览器相关实践记录
- 编程笔记索引 — 其他语言与工程实践