为什么印出来的二维码扫不出:在下载前建一道解码与物理校验闸门

· 14 分钟 · 系统工程 二维码校验jsqrcanvas打印无障碍性能预算

二维码是死在纸上,不是死在屏幕上

我为小商家维护的工具集——税率计算、电子发票校验、PDF 处理——最后总绕回同一个物件:二维码。店主要把码印在桌面立牌上、名片上、货车车身上、收据上。需求永远是同一句话:这个码能用,帮我印。

这份工作的诚实版本并不是画方块,而是交出一个在它要去的那个表面上扫得出来的文件。而这类需求里最贵的两种失败,浏览器能做的检查全都看不出来。一个在 400 像素画布上解码完美的符号,印到纸上每个模块只有 0.29 毫米,任何手机相机的中央区域都找不到它。一个深红色的码,对比度算下来 10.9:1,可访问性工具一声不响地放行,而柜台那把红光扫描枪看到的是一张白纸。

所以这个工具只有一条不可协商的规则:jsQR 没有把即将导出的符号解码、并且把载荷一字不差地读回来之前,下载按钮就是灰的。 不是预览一张“应该能读”的图,而是从导出用的同一条矢量路径重新上墨,并用一个刻意不同于页面自身结论的 decoder import 来读它。

引擎本身没什么稀奇:六种载荷(文本/网址、Wi-Fi、vCard 3.0、tel:、SMSTO:、mailto:)、四种模块形状、三种定位图案形状、前景色与背景色加可选的双色渐变、以毫米计的尺寸、L 到 H 的纠错等级、可选中心图、可选说明文字,导出为带真实 pHYs 块的 300 dpi PNG 和 SVG。

值得写下来的是闸门,因为这道闸门在变对之前,错了四次。

闸门容易,可信才难

第一版直接解码导出的位图。它立刻失败,而且失败得很有教育意义:平滑重采样或最近邻缩放会把点状模块之间那一像素的缝隙抹掉,结果一个印在纸上完全正常的码,仅仅因为测试环节重采样的方式不对,就被误判拦截了。闸门必须用导出器用的同一个 shapePath,按选定的像素密度重新上墨,而不是缩放一张它的照片。

第二版做了最直觉的事:按打印分辨率去探测。300 毫米的导出就是每个模块 95 像素、横向 3500 像素,而在 150、200、300 毫米三档实测里,同一种点状模块在更小的每一档都能解码,超过这附近就开始解不出来。jsQR 是给照片写的解码器——几百像素见方——它有自己的工作区间。按 95 像素/模块去探测,测的是解码器的舒适度,不是设计的正确性。

第三版反过来只用一个低密度,8 像素/模块,那是一个 25 毫米名片实际给出的密度。它从另一边坏掉:一个在 8 像素/模块下读得干净的点阵,在 20 像素/模块下可能解不出来——jsQR 先用 8×8 的自适应二值化块求局部阈值,再在模块几何中心单点采样,某些密度下这套采样网格会和圆点之间的白缝产生混叠。只用一个密度就判死刑,等于让好的设计替解码器的盲区背锅。

上线的那版把符号用两个密度交给解码器——访问者自己选的密度(上限 24 像素/模块)和 8 像素/模块——只有两个都失败才拒绝:

const nativePitch = Math.max(1, Math.floor(canvas.width / geo.total));
const pitches = [...new Set([
  Math.min(nativePitch, PROBE_PITCH_MAX),
  Math.min(nativePitch, PROBE_PITCH_MIN),
])];

let found: string | null = null;
let tried = 0;
for (const pitch of pitches) {
  const side = geo.total * pitch;
  if (side < 21) continue;
  tried += 1;
  probe.width = side;
  probe.height = side;
  pctx.imageSmoothingEnabled = false;
  const scaled = centre ? rescaleCentre(centre, pitch / modulePx) : null;
  paintSymbol(pctx, pitch, geo, gradient, scaled, inkDark, inkLight);
  const pixels = pctx.getImageData(0, 0, side, side);
  const hit = decode(pixels.data, side, side, { inversionAttempts: 'dontInvert' });
  if (!hit) continue;
  found = hit.data;
  if (verifyDecode(expected, found) === 'ok') return 'ok';
}
if (tried === 0) return 'empty';
return found === null ? 'mismatch' : verifyDecode(expected, found);

这一节还有一条排除规则:说明文字的条带不画进探针。码下面的字是字,不是码的一部分;在 80 毫米及以上,那些字形的笔画给 jsQR 提供了足够多的伪定位候选,以至于一个在 50 毫米能解的圆眼设计,到 80 毫米就解不出来。因为说明文字而失败的闸门,量错了对象。

干净位图看不见的四件事

闸门诚实之后,工具仍然会送出在现实世界里注定失败的码,因为一张 8 像素/模块的干净位图,有一组非常具体的盲区。下面每一条现在都是带实测数字的规则。

一、模块下限。 一个 61 模块的载荷——带电话和地址的 vCard——印在 20 毫米上,加上两侧各四个模块的固定静区就是 69 个模块:纸面上每个模块 0.29 毫米。闸门把同一个符号按 8 像素/模块重新上墨,解得出来,于是放行,而做出来的贴纸在过塑立牌上无人可扫。油墨扩散、碳粉散点、微距对焦全都在解码器永远不会越过的这条线以下。现在 pitchCheck 会拒绝每模块细于 0.40 毫米的打印件,点状与柔和圆角则为 0.50 毫米——它们在每个缝隙处都漏墨——并且引用它量到的毫米数,而不是它套用的限值。

二、中心图是面积问题,不是边长问题。 H 级纠错大约能找回 30% 的码字,而这份预算不只给 logo:它还要让这个码扛住一个指纹、一片反光、一道折痕、一只斜着举起的手机。29 模块的符号放 30% 的中心图,看着很保守,直到把两侧各两个模块的白色挖空留白算进去:占边长 43.8%、占面积 19%——相当于在一个仅靠干净位图测出回读余量的符号上,硬生生挖掉了近五分之一的面积。现在上限是 含留白在内的 15% 面积(CENTRE_MAX_AREA),于是同一个 30% 的滑杆,在密集的 vCard 上放行,在短网址上拒绝。这是物理,不是口味。

三、被柜台枪当成白纸的红墨。 WCAG 相对亮度给绿色 0.7152、给蓝色 0.0722 的权重,所以白底上的深红 #800000 拿到 10.9:1,轻松越过 4.5:1 的闸门。只看原始 8 位红色通道(这也是闸门的算法口径)是 1.9:1——而 660 纳米红光扫描枪,那种至今还锁在柜台上的,恰好在这个波段上是色盲。手机读红墨毫无困难,所以这一条只警告、绝不拒绝:文件照样可下载,句子会写出那个比值,选择权归打印的人。

四、毫米级尺寸契约:整数像素、说明文字条带与 pHYs 块。 300 dpi 下一个模块只能是整数个像素;以 29 模块的符号(含两侧各四个模块静区,共 37 模块)为例,规划器向上取整,不向下:ceil(box / (modules + 2 × quiet))。向下取整会把 25 毫米那一档印成 21.9 毫米,正好落在这页自己警告的下限之下;向上取整只会让码比要求的大,而这对相机来说是安全的方向。要求 50 毫米,落成 50.1 毫米,这个符号的导出是 592 像素见方。说明文字再加一条占码宽 13% 的带——那个密度下是五个模块,也就是 6.77 毫米——所以文件报的是 50.1 × 56.9 毫米:码是方的,纸不是。pHYs 块把同一份承诺带出浏览器:没有它,文字处理器退回 96 dpi,把那 592 像素摆成 157 毫米,正好是立牌预订尺寸的三倍。

🔍 解码器看不见的两条规则:pitchCheck 与中心图面积上限(TypeScript,30 行)
export const MIN_MODULE_MM = 0.4;
export const MIN_MODULE_MM_DOTS = 0.5;

export interface PitchCheck {
  ok: boolean;
  mm: number;
  floor: number;
}

/** Judge the module pitch of the print, not of the preview. */
export function pitchCheck(totalModules: number, actualMm: number, style: QrStyle): PitchCheck {
  const floor = style === 'dots' || style === 'soft' ? MIN_MODULE_MM_DOTS : MIN_MODULE_MM;
  const mm = totalModules > 0 ? actualMm / totalModules : 0;
  return { ok: mm + 1e-9 >= floor, mm: Number(mm.toFixed(3)), floor };
}

export const CENTRE_MAX_RATIO = 0.3;
/** Share of the symbol's *area* the knockout may cover, pad included. */
export const CENTRE_MAX_AREA = 0.15;
export const CENTRE_PAD_MODULES = 2;

// inside planCentre()
const ratio = percent / 100;
const sidePx = Math.max(1, Math.round(input.codePx * ratio));
const padPx = Math.max(0, input.modulePx) * CENTRE_PAD_MODULES;
if (ratio > CENTRE_MAX_RATIO + 1e-9) problems.push('too-large');
// The pad is not decoration: it is four more modules of code that no longer exist.
const knockoutSide = sidePx + padPx * 2;
const occupied = input.codePx > 0 ? (knockoutSide / input.codePx) ** 2 : 1;
if (occupied > CENTRE_MAX_AREA + 1e-9) problems.push('too-much-area');

上述每一条规则都跑在生成文件的那个页面上:tools.hoelee.com 的二维码生成器 会在文件离开浏览器之前拦下过细的模块密度和超标的中心图挖空,让印刷下厂不再靠碰运气。四种失效并排对照:

现实世界里的失效浏览器检查看到什么闸门规则
61 模块的 vCard 印在 20 毫米8 像素/模块回读通过每模块细于 0.40 毫米(点状 0.50 毫米)即拒
29 模块符号加 30% 中心图干净位图 H 级解码通过含留白面积超过 15% 即拒
白底深红 #800000WCAG 10.9:1,越过 4.5:1红通道 1.9:1 → 只警告,不拒绝
300 dpi PNG 缺 pHYs浏览器里显示正常写入该块,按 50.1 × 56.9 毫米报尺寸

证明闸门真的关得上

没人看着关上的闸门,不算闸门。引擎测试证明算术,Playwright/CDP 探针证明页面,而且它刻意不信任页面自己的结论:它先找出码的黑色外接框,校验时序行与时序列——任何缩放、拉伸、裁切或平移错位(mistranslate)的图形都会在这里暴露,哪怕 jsQR 还能勉强猜出载荷——随后独立加载站点的按需 jsQR 分包,直接读取画布原始像素完成解码。只有作者自己能读的符号,在这里过不了。

闭合性测试是为这件事专门留的接缝:给控件设 data-simulate-mismatch="1",回读会被喂一个错字符串,探针断言下载消失。闸门必须扣住文件,而不只是嘴上说要扣。

这个探针抓到三件顺风路径看不见的事:

那条在替版面说好话的检查。 同站的图像工具把舞台放在表单旁边,所以它们的约定是“下载在第一屏”。这个工具把码放在六类表单下面,而探针的第一版调用 scrollIntoView 把下载块滚进视野再测量,以此断言同一条规则——那量的是“已经滚到那里之后能不能放进视口”,不是“在第一屏”。诚实的属性是:按钮就在码下方一眼的位置,用页面坐标测量,滚动帮不上忙——390 像素宽时,下载块在码下方 66 像素、高 48 像素,横向溢出 0 像素;1440 像素宽时是两栏各 518 像素,码位于 x = 719。把被测对象先滚进视野再量的闸门,不算闸门。

🔍 探针自己的解码器:不依赖控件的回读(Python + 注入 JS,24 行)
# The probe's own decoder: the page's own lazy jsQR chunk, imported fresh. The canvas is drawn
# from the page's pixels at their native resolution — nothing resampled, nothing smoothed — and
# only the symbol square is read, because the caption band below it is type, not code.
DECODE_JS = """(async () => {
  try {
    const src = document.querySelector('[data-qr]');
    if (!src || !src.width) return { found: null, note: 'no canvas' };
    const w = src.width, h = src.width;
    const c = document.createElement('canvas');
    c.width = w; c.height = h;
    const ctx = c.getContext('2d', { willReadFrequently: true });
    ctx.imageSmoothingEnabled = false;
    ctx.drawImage(src, 0, 0, w, h, 0, 0, w, h);
    const img = ctx.getImageData(0, 0, w, h);
    const chunk = performance.getEntriesByType('resource').map(e => e.name).find(n => /jsQR/i.test(n));
    if (!chunk) return { found: null, note: 'no jsqr chunk' };
    const mod = await import(chunk);
    const fn = mod.default;
    const hit = fn(img.data, w, h);
    return { found: hit ? hit.data : null, size: [w, h] };
  } catch (e) {
    return { found: null, note: 'decode threw: ' + String(e) };
  }
})()"""

一个只画码的页面,替一个电话解析器付了钱

这一轮最后一项失败和二维码毫无关系,和预算怎么失败关系很大。三条二维码路由是站上最重的——78.7 到 79.6 KB,对 80 KB 预算——而新加的四句警告文案把它们推到 80.1–81.4 KB,npm run verify 直接失败。文案不可能值 2 KB。

原因是 import 图。二维码生成器的引擎从 WhatsApp 链接生成器的引擎里导入绘图辅助函数,而那个模块在顶层就引了 libphonenumber-js:28.7 KB 的电话解析,由一个只画码的页面付账。绘图那一半移进了 whatsapp-link-builder/qr-core.ts,再从 engine.ts 重新导出,让所有既有 import 照旧工作,二维码工具直接引 qr-core。三条路由降到大约 53 KB,站上最重的路由现在是 WhatsApp 链接生成器的 75.7 KB。

可迁移的那部分是:只剩 1.3 KB 余量的预算不是预算,是倒计时。它一定会栽在一次文案修改上,而 diff 会指向那段文案。在怪句子之前,先读 import 图。

结果

我会再做一次的选择

这件事里真正的价值不在于 jsQR。而在于接受一件事:解码器回答的,是一个比真正重要的问题更窄的问题。jsQR 能告诉我这个符号内部自洽——模块对、载荷对、没被剪切、没被译错。它没法告诉我打印机是否把这些模块放得够开,能不能扛住油墨;没法告诉我 logo 的挖空是否还留给纠错预算足够余量去应付一个指纹;也没法告诉我这种油墨在柜台上那把扫描枪的波长上是否吸光。

所以让这个工具能用的规则,全是量在纸上的下限与预算:每模块 0.40 毫米、15% 面积、四个模块且不可调节的静区、红色通道对比只作为警告而不设墙。每一次拒绝都引用它量到的数字——“每模块 0.29 毫米”,而不是“太小了”——因为把限制说成限制教不会任何东西,而拿着文件的那个人需要知道离印得出来还差多远。

探针那一条,是我在别的形状里反复重新学到的:一个能被“做校验的那段代码”自己满足的校验,不是校验。给闸门喂一个错字符串,看下载消失。按读者拿到它的方式去量版面,而不是按断言偏好的方式先把版面摆好。

🛡️ 生产级基础设施与系统架构

服务器频繁异常重启、云账单过高,或缺一位能穿透内核日志的架构师?

真正的生产环境稳定性,靠的是穿透表象抓出根因。我独立管理着跨 3 台物理/云主机、162 个容器的高可用自托管生产网络。

Lee Teong Hoe

Lee Teong Hoe · Mr Hoelee

Full-stack developer & DevOps engineer based in Malaysia. I run my own production infrastructure and build web systems for small businesses — this blog is the living record.

Hiring? Profile & stack · Malaysian SME? Website design & development ↗ · All posts