线上工具站跑了几个月,二维码这块的反馈特别集中,而且基本都是同一句话:"这个码扫不出来"。
一开始我以为是解码库不行,换过两个,结果一样。后来把用户传上来的几十张"扫不出"的图逐张分析,才明白问题不在解码器,在于我们喂给它的东西不对:一张 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 必须上 H 纠错,然后就爆容量了
给二维码中间贴 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),解码全程在浏览器完成,图片不上传服务器。代码就是上面这些,没有黑魔法。