为什么印出来的二维码扫不出:在下载前建一道解码与物理校验闸门
二维码是死在纸上,不是死在屏幕上
我为小商家维护的工具集——税率计算、电子发票校验、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% 即拒 |
白底深红 #800000 | WCAG 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",回读会被喂一个错字符串,探针断言下载消失。闸门必须扣住文件,而不只是嘴上说要扣。
这个探针抓到三件顺风路径看不见的事:
- 一张在加载时被拒的中心图——900 像素,超过 600 像素上限——会静默退回“没有中心图”的码,并且照样给出下载。这正是载荷规则禁止的静默丢弃。现在被拒的文件在清除或替换之前,一直扣着导出。
- vCard 的 CRLF 在 textarea 里看不见,因为浏览器读取时把值规范成了 LF。探针改成对输入框折叠换行,转而在解码后的画布上证明 CRLF。
- 探针跑到一半时重新构建(
astro build在astro preview供页时替换dist/)会让一个检查报红,然后因为拿不到几何数据崩掉整轮。探针运行期间不要重新构建;探针应当把缺失的页面报成失败,而不是抛 traceback。
那条在替版面说好话的检查。 同站的图像工具把舞台放在表单旁边,所以它们的约定是“下载在第一屏”。这个工具把码放在六类表单下面,而探针的第一版调用 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 图。
结果
- 238 + 954 个测试通过,其中 67 个属于二维码引擎(本轮新增 10 个)。
- 157 个页面构建成功,
astro check0 错误,bundle 预算绿色。 probe_qr_code的 300 项校验在构建产物上全绿,在线上站点再全绿一次。probe_a11y的 234 项校验全绿,包含三个语种的二维码页。- 模块拆分之后
probe_whatsapp_link结果不变——这条检查证明这次重构搬了代码、没搬行为。 - 最重的二维码路由从 80.1–81.4 KB 降到 约 53 KB,预算仍是 80 KB。
我会再做一次的选择
这件事里真正的价值不在于 jsQR。而在于接受一件事:解码器回答的,是一个比真正重要的问题更窄的问题。jsQR 能告诉我这个符号内部自洽——模块对、载荷对、没被剪切、没被译错。它没法告诉我打印机是否把这些模块放得够开,能不能扛住油墨;没法告诉我 logo 的挖空是否还留给纠错预算足够余量去应付一个指纹;也没法告诉我这种油墨在柜台上那把扫描枪的波长上是否吸光。
所以让这个工具能用的规则,全是量在纸上的下限与预算:每模块 0.40 毫米、15% 面积、四个模块且不可调节的静区、红色通道对比只作为警告而不设墙。每一次拒绝都引用它量到的数字——“每模块 0.29 毫米”,而不是“太小了”——因为把限制说成限制教不会任何东西,而拿着文件的那个人需要知道离印得出来还差多远。
探针那一条,是我在别的形状里反复重新学到的:一个能被“做校验的那段代码”自己满足的校验,不是校验。给闸门喂一个错字符串,看下载消失。按读者拿到它的方式去量版面,而不是按断言偏好的方式先把版面摆好。
服务器频繁异常重启、云账单过高,或缺一位能穿透内核日志的架构师?
真正的生产环境稳定性,靠的是穿透表象抓出根因。我独立管理着跨 3 台物理/云主机、162 个容器的高可用自托管生产网络。