thumbhash 解码后必须转为 data url 才能用作 css background，直接使用 uint8array 会因浏览器不识别而静默失败；服务端生成时宽高须与实际 rgba 数据严格匹配，否则导致比例失真或颜色偏移；移动端需 off-main-thread 解码防卡顿。
ThumbHash 解码后必须转成 data URL 才能当 background
直接把 Uint8Array 当 CSS 背景用会报错，浏览器不认识二进制哈希值。得先调用 thumbHashToDataURL 转成 data:image/png;base64,... 格式，再塞进 background-image。
常见错误是跳过这步，直接写 element.style.background = hash，结果背景空白、控制台没报错但图像不显示——因为 CSS 解析失败被静默忽略。
-
thumbHashToDataURL返回的是完整可渲染的 data URL，不是 raw bytes - 若用
thumbHashToRGBA自己画 canvas，要额外调canvas.toDataURL("image/png")，别漏 MIME 类型 - 某些旧版 Safari 对超长 data URL 渲染有延迟，建议 ThumbHash 字节数控制在 32 以内（实际 20 字节足够）
img 标签本身不能直接用 ThumbHash，必须靠容器兜底
<img> 标签的 src 只接受 URL 或 data URL，不支持 ThumbHash 二进制或 base64 编码后的原始哈希值。强行赋值会导致加载失败、触发 error 事件。
正确做法是：用一个带明确尺寸的 <div> 容器，把 ThumbHash 解码后的 data URL 设为它的 <code>background-image，真实图片则放在内部 <img> 中，靠 load 事件切换显隐。
- 容器必须设
width和height，或aspect-ratio，否则背景图拉伸/裁切不可控 - 别给
<img>设opacity: 0就完事——要监听error，失败时 fallback 到背景图或占位图 - 如果用了
loading="lazy"，load事件仍会触发，但首次滚动前不会解码 ThumbHash，需预加载哈希值
服务端生成 ThumbHash 时宽高必须和原图一致
rgbaToThumbHash 函数依赖原始图像的 w 和 h 参数。若服务端用 Sharp 缩放后再传给 ThumbHash，但没同步更新宽高参数，解码出的占位图会出现严重比例失真或颜色偏移。
典型场景：Node.js 后端读取一张 1200×800 的 JPG，用 Sharp 缩到 300×200 再送进 rgbaToThumbHash，却仍传 w=1200, h=800 —— 这会导致解码时按 1200×800 分配像素内存，实际数据只有 300×200，后面全是越界填充噪声。
- 务必保证传入
rgbaToThumbHash的w/h与实际 RGBA 数组长度匹配：rgba.length === w * h * 4 - Sharp 处理后记得调
metadata()拿真实输出尺寸，别硬编码 - Rust/Java 版本同理，
rgba_to_thumb_hash不做宽高校验，出错不报，只默默渲染异常
移动端 WebView 里 ThumbHash 解码可能卡顿，要 off-main-thread
iOS WKWebView 和 Android WebView 在主线程解码 ThumbHash（尤其多图列表）会造成滚动掉帧。JavaScript 版本的 thumbHashToRGBA 是纯 CPU 计算，没有自动 Web Worker 封装。
这不是算法问题，而是执行时机问题：在 scroll 或 requestIdleCallback 里批量解码，比 onload 立即解码更稳。
- 优先用 Rust/WASM 版本（如
@thumbhash/wasm），它默认启用多线程 SIMD 加速 - 若只能用 JS 版，把解码逻辑包进
setTimeout(..., 0)或queueMicrotask，避免阻塞渲染 - Android 上某些低端机型对
Uint8Array创建开销敏感，复用 ArrayBuffer 比每次都 new 更省
真正容易被忽略的地方是：ThumbHash 占位图的视觉合理性，取决于原始图像是否经过 gamma 校正处理。未经校正的 sRGB 像素直接喂给 rgbaToThumbHash，会导致暗部细节丢失——这点在服务端批量处理时几乎没人检查。
