为什么越清晰的二维码越扫不出来:jsQR 四轮解码与 8 个真实坑

线上工具站跑了几个月,二维码这块的反馈特别集中,而且基本都是同一句话:"这个码扫不出来"。

一开始我以为是解码库不行,换过两个,结果一样。后来把用户传上来的几十张"扫不出"的图逐张分析,才明白问题不在解码器,在于我们喂给它的东西不对:一张 12MP 的手机照片、一张透明背景的 PNG、一张存成了 JPEG 的码图,解码器再强也读不出来。

这篇把生成端和识别端的坑一起写下来,都带可直接抄的写法。


先说结论:扫不出分两类

  • 图本身坏了:JPEG 有损压缩把模块边缘糊掉、quiet zone 被裁掉、反色、贴了 logo 但纠错级别不够。
  • 读的方式不对:给解码器喂了过大的图、码只占画面一小块、透明背景被合成成了黑底、手机照片带着 EXIF 旋转。

第二类占多数,而且完全可以在代码里修掉。


坑一:越清晰的图越扫不出

这是最反直觉的一条。用户拍了一张很清楚的二维码照片,4000×3000,丢进解码器转半天,返回 null。

原因是 jsQR 这类解码器是逐像素扫描的:它要在二值化后的图里找定位图案(三个角的回字形),图越大,扫描越慢,而且噪声越多,定位反而更容易失败。

我的做法是先降采样到长边 1024 再解:

js 复制代码
const canvas = document.createElement('canvas');
const context = canvas.getContext('2d', { willReadFrequently: true });

canvas.width = 1024;
canvas.height = Math.round((bitmap.height / bitmap.width) * 1024);
context.imageSmoothingEnabled = true;
context.imageSmoothingQuality = 'high';
context.drawImage(bitmap, 0, 0, canvas.width, canvas.height);

const pixels = context.getImageData(0, 0, canvas.width, canvas.height);
const found = jsQR(pixels.data, pixels.width, pixels.height);

willReadFrequently: true 不是玄学,它让浏览器把 canvas 放在内存里而不是 GPU 纹理上,getImageData 才不会每次都回读显卡、慢十倍。


坑二:码只占画面一小块,得裁

用户截图经常是这样的:一屏聊天记录,中间夹着一个 150px 的二维码。整图缩到 1024 之后,那个码只剩 40px,定位图案彻底糊了。

所以第二轮要裁中心区域再放大。我把识别拆成四轮,从便宜到贵:

js 复制代码
export function buildDecodePlan(width, height) {
  const longEdge = Math.max(width, height);
  const plan = [
    { label: 'fit',    targetEdge: 1024, crop: null },  // 常规图,一次搞定
    { label: 'centre', targetEdge: 1024, crop: 0.6 },   // 码在中间那一块
  ];
  if (longEdge > 1024) plan.push({ label: 'detail', targetEdge: 1600, crop: null });
  if (longEdge > 1600) plan.push({ label: 'zoom',   targetEdge: 1200, crop: 0.35 });
  return plan;
}

fit 处理九成情况;centre 救截图;detail 和 zoom 专门对付"大图里的小码"------先取中心 35% 再放大到 1200,等于对这个区域做了 3 倍插值。

命中第几轮我会记下来返回给页面,用户能看到"这张图是靠放大才读出来的",体验上也说得过去。


坑三:透明背景的 PNG,会吞掉 quiet zone

二维码规范要求四周留白(quiet zone,通常 4 个模块宽)。用户从设计稿导出的 PNG 经常是透明底,drawImage 到 canvas 上之后,透明区域在 getImageData 里是 rgba(0,0,0,0) ------ 合成后就是黑的。

结果:四周留白变黑,和白底码的对比度彻底反转,定位失败。

一行修复,先铺白底:

js 复制代码
context.fillStyle = '#ffffff';
context.fillRect(0, 0, canvas.width, canvas.height);
context.drawImage(bitmap, ...);

这个细节在很多实现里没有,用户传透明底 PNG 就必挂。


坑四:手机照片是躺着的

iPhone 拍的照片,像素数据常常是横的,方向写在 EXIF 里,看图软件会自动转,canvas 不会。

createImageBitmap 有个参数专门干这个:

js 复制代码
const bitmap = await createImageBitmap(file, { imageOrientation: 'from-image' });

少了这一句,一张竖着拍的码图喂进去就是旋转 90° 的,怎么都扫不出。而用户完全无法理解"为什么我手机能扫、你网站不能"。

顺带一提,Safari 早期不支持 createImageBitmap 的 options,所以要留一条 new Image() + URL.createObjectURL 的退路。


坑五:反色码

深底浅码(黑底白块)是合法的二维码,但 jsQR 默认只找"深色模块",反色的直接漏掉。它有个开关:

js 复制代码
const found = jsQR(pixels.data, pixels.width, pixels.height, {
  inversionAttempts: 'attemptBoth',
});

代价是每轮多扫一遍,慢一点;但比起让用户对着屏幕怀疑人生,这点开销值。


坑六:把二维码存成 JPG

这条是生成端的锅,也是最冤的。

二维码是一堆锐利的黑白方块,JPEG 的 DCT 会在边缘产生振铃(ringing),模块之间糊成一团灰。屏幕上看还挺清楚,一扫就废。二维码必须存 PNG(或 SVG),永远不要 JPEG。

生成时直接拿 canvas 的 PNG:

js 复制代码
const url = canvas.toDataURL('image/png');

如果做的是"下载二维码",更推荐导 SVG:无论打印多大都锐利,体积还小。


给二维码中间贴 logo 是刚需,很多人生成完发现扫不出,原因就在这。

二维码有四个纠错级别:L 7%、M 15%、Q 25%、H 30%。logo 遮住中心大约 5% 的面积,看起来 M 够用------但中心区域还压着格式信息和部分定位数据,实际只有 H 还有余量。所以贴 logo 时我会强制切到 H:

js 复制代码
// A logo covers real data. M tolerates 15%; the patch is about 5% of the
// area but sits in the middle where the format information also lives,
// so H is the only level with margin left over.
setEcLevel('H');

代价是容量。同样的内容,H 级别要比 L 多占不少模块,版本号一升再升。极端情况是内容本身很长(比如一大段 JSON),切到 H 之后任何版本都放不下------QR 规范的版本 40 上限大约是 2.9 KB 的字节数据,超了就是无解,只能缩短内容或降级纠错。

所以生成端要做的是:贴 logo → 强制 H;内容放不下 → 明确报错告诉用户"内容太长",而不是默默生成一个扫不出的图。


坑八:quiet zone 被用户裁掉了

用户截图的时候习惯把白边裁掉"显得紧凑",这一步直接把 quiet zone 干掉。没有留白,扫码器找不到码的边界。

生成端默认 margin 给 4 个模块,并且提供 0/2/4/8 的选项------给 0 是给设计场景用的(他们要在别处自己留白),但默认绝不能是 0。


完整流程

识别端最终是这样:

js 复制代码
for (const step of buildDecodePlan(width, height)) {
  const geometry = stepGeometry(width, height, step);  // 裁哪块、画多大
  canvas.width = geometry.dw;
  canvas.height = geometry.dh;
  context.fillStyle = '#ffffff';                       // 坑三
  context.fillRect(0, 0, geometry.dw, geometry.dh);
  context.imageSmoothingQuality = 'high';              // 坑一
  context.drawImage(bitmap, geometry.sx, geometry.sy, geometry.sw, geometry.sh,
                    0, 0, geometry.dw, geometry.dh);

  const pixels = context.getImageData(0, 0, geometry.dw, geometry.dh);
  const found = jsQR(pixels.data, pixels.width, pixels.height, {
    inversionAttempts: 'attemptBoth',                  // 坑五
  });
  if (found?.data) return { text: found.data, pass: step.label };
}

另外两个工程细节:

  • jsQR 有 40 KB,只在用户真的丢图进来时才 import(),不占首屏。
  • 10 张 12MP 图同时解码会把主线程卡死,所以队列串行跑,一张解完再下一张。

一句话总结

二维码扫不出来,九成不是"码坏了",是喂给解码器的东西不对:太大、太偏、太透明、太歪、太糊。把降采样、裁中心、白底、EXIF、反色这几件事做掉,识别率能从"经常失败"变成"基本一次过"。

这套逻辑现在跑在一个纯前端的在线工具里(moying.xin),解码全程在浏览器完成,图片不上传服务器。代码就是上面这些,没有黑魔法。

相关推荐
小y的笔记26 分钟前
Vue 3 异步搜索实战:watch、请求取消与竞态控制
前端·javascript
用户298698530143 小时前
React 前端实现 Excel 与 HTML 双向转换:基于 WebAssembly 的浏览器端方案
javascript·html·excel
1-1=03 小时前
Vue 表单数据和过滤器
前端·javascript·vue.js
头发还在的女程序员4 小时前
智慧物业源码解析:房屋档案与业主变更怎样保持历史业务连续
前端·javascript·vue.js·物业管理·小区物业·智慧物业
feixing_fx13 小时前
第一个 JS 程序:在浏览器控制台和 Node 中分别运行
开发语言·前端·javascript·前端框架·ecmascript
feixing_fx14 小时前
变量与声明:let、const、var 的选择边界
开发语言·前端·javascript·前端框架
程序员大阳14 小时前
副队长Vue3教程(8)--列表渲染 v-for
javascript·vue3·v-for·列表渲染
feixing_fx18 小时前
JavaScript 是什么:从浏览器脚本到通用编程语言
开发语言·前端·javascript·前端框架·ecmascript
小y的笔记18 小时前
JavaScript URL 状态同步
前端·javascript