二维码解码失败:反相、缩放与 Canvas 时机

2026-11-19 前端开发 有希 33 次浏览

同一张二维码,手机相机一扫就开,网页上传后却返回空;或者在生成页里怎么改内容都没有图。前者通常是像素处理的问题,后者往往和 Canvas 挂载时机有关,跟二维码内容无关。

先给结论

静态图片解码失败,先按这三个方向排查:

  1. 反相:深色背景、白色模块的二维码,需要按反相再扫一次。jsQR 1.4.0 默认已经这么做了,先确认你的封装有没有重复处理。
  2. 缩放:把长边压到 1600 能显著减少像素量,但二维码在画面里很小时会把模块压没。第一轮失败必须回原图。
  3. Canvas 时机:二维码画不出来、预览区空白,优先怀疑容器节点还没进入 DOM,而不是编码参数。

可以直接在 二维码解码工具 里复现前两类问题,生成侧的绘制参数则可以在 艺术二维码工具 对照。

三类典型失败现象

现象更可能的原因怎么确认
手机能扫,网页返回 null反相未覆盖,或缩放过度换正相/反相两张图分别上传
只有截图能解,拍照图不行缩放后模块太小,或图片模糊观察二维码在画面中的占比
生成页预览永远空白Canvas 容器尚未挂载看控制台是否有节点为 null
粘贴图片没反应剪贴板没有 image 类型或权限被拒换文件选择器验证
解码出乱码内容编码不是 UTF-8看原始字节与生成端编码

第一类和第三类最容易被误判成“库不支持”。先把现象分开,后面的排查才有意义。

反相:库已经做了,不要再做一遍

jsQR 的入口在 node_modules/jsqr/dist/jsQR.js。它把默认配置定义在模块级对象里:

var defaultOptions = {
  inversionAttempts: "attemptBoth",
};

function jsQR(data, width, height, providedOptions) {
  if (providedOptions === void 0) { providedOptions = {}; }
  var options = defaultOptions;
  Object.keys(options || {}).forEach(function (opt) {
    options[opt] = providedOptions[opt] || options[opt];
  });
  var shouldInvert =
    options.inversionAttempts === "attemptBoth" ||
    options.inversionAttempts === "invertFirst";
  var tryInvertedFirst =
    options.inversionAttempts === "onlyInvert" ||
    options.inversionAttempts === "invertFirst";
  var _a = binarize(data, width, height, shouldInvert);
  var result = scan(tryInvertedFirst ? _a.inverted : _a.binarized);
  if (!result && options.inversionAttempts === "attemptBoth") {
    result = scan(tryInvertedFirst ? _a.binarized : _a.inverted);
  }
  return result;
}

几个关键点:

  • 默认值是 attemptBoth,也就是先扫正相,失败再扫反相;
  • 反相图不是靠再画一遍得到的,而是在二值化阶段同时产出正相和反相两张位图;
  • 这段代码把 defaultOptions 直接赋给 options,传参时会写回默认对象。也就是说,调用方传一次 { inversionAttempts: 'onlyInvert' },后续所有不传参的调用都会沿用这个值。

最后一点是个隐蔽的坑。如果你在某个页面为了调试传过一次反相参数,其他页面的行为可能一起变了。要么每次调用都显式传完整参数,要么干脆不传,使用默认值。

门户的解码函数在 app/utils/qrcode.ts,目前的尝试顺序是:

const attempts: Array<{ w: number; h: number; invert: boolean }> = []
const pushAttempts = (w: number, h: number) => {
  attempts.push({ w, h, invert: false }, { w, h, invert: true })
}
if (scale < 1) pushAttempts(scaledWidth, scaledHeight)
pushAttempts(bitmap.width, bitmap.height)

for (const attempt of attempts) {
  const image = await drawToCanvas(bitmap, attempt.w, attempt.h)
  if (attempt.invert) invertImageData(image)
  const found = jsQR(image.data, image.width, image.height)
  if (found?.data) return found.data
}

这里每个尺寸都手动传了反相和非反相两次,再加上 jsQR 自身的 attemptBoth,实际会多扫一轮。功能上不影响结果,但每次尝试都要新建 Canvas、getImageData、复制一份像素并循环取反,失败路径的成本会翻倍。更简单的做法是只保留尺寸维度,让库自己处理正反相;如果确实需要控制扫描顺序,再显式设置 inversionAttempts,并注意上面提到的默认对象被改写的问题。

实测正相与反相两张二维码,门户都能解出同一内容:

正相二维码 -> https://example.com/qr-test
反相二维码 -> https://example.com/qr-test

所以遇到反相图解不出时,先看版本和参数,不要急着再写一个 invert 循环。

缩放:先加速,失败回原图

jsQR 接收的是 Uint8ClampedArray,大小为 width × height × 4。一张 4000×3000 的截图,RGBA 数据约 48 MB;压到长边 1600 后约 7.7 MB,像素量差了六倍多。二值化和定位都要遍历这些数据,缩放对交互体验的影响很直接。

但缩放不是越小越好。二维码的模块需要足够的像素才能被定位和采样。如果一张 4K 截图里二维码只占右下角 300×300,压到长边 1600 后,二维码可能只剩一百多像素,模块之间糊在一起,第一轮就会失败。

门户的策略是“缩放图优先,原图兜底”:

const scale = Math.min(1, DECODE_MAX_EDGE / Math.max(bitmap.width, bitmap.height))
if (scale < 1) {
  // 先试缩放图,正常与反相各一次
}
// 再试原图

单页工具的写法略有不同。app/pages/toolkit/qr-decode/index.vue 里只压一次,MAX_SIDE = 1600,然后直接调用:

const scale = Math.min(1, MAX_SIDE / Math.max(bitmap.width, bitmap.height))
const width = Math.max(1, Math.round(bitmap.width * scale))
const height = Math.max(1, Math.round(bitmap.height * scale))
ctx.drawImage(bitmap, 0, 0, width, height)
const { data } = ctx.getImageData(0, 0, width, height)
const result = jsQR(data, width, height, { inversionAttempts: 'attemptBoth' })

这里没有原图回退。对“整张图就是二维码”的场景足够,但如果用户上传的是整页截图,二维码只占一小块,就该补一次原图重试。判断标准不是图片总尺寸,而是二维码在画面里的占比:缩完后模块仍清晰,就可以只跑一轮;否则必须回原图。

另外,createImageBitmap(file, { imageOrientation: 'from-image' }) 会按 EXIF 方向解码。手机横拍的照片如果方向不对,二维码会旋转甚至镜像,虽然部分情况下仍能扫出,但会增加失败率。这个参数与图片工具里的处理一致,原因写在 Canvas 照片方向 里。

Canvas 时机:插槽不是 mounted 就有

生成页 qr-style 的二维码画在 <ClientOnly> 里。页面代码里有一段注释,记录过一次真实的空白问题:

/**
 * 挂载时机要注意:二维码容器在 <ClientOnly> 里,而 ClientOnly 自身的 mounted 才把
 * 插槽渲染出来 —— 父组件的 onMounted 早于它,那一刻 canvasHost 还是 null,
 * 在这里直接 append 会静默什么都不画。所以改成 watch ref,等节点真正出现再挂。
 */
watch(
  canvasHost,
  (el) => {
    if (!el) return
    instance = new QRCodeStyling(buildOptions())
    instance.append(el)
  },
  { immediate: true }
)

ClientOnly 的插槽内容要等组件挂载后、状态更新并重新渲染才会出现,这个更新发生在下一轮渲染,不是在父组件 onMounted 的那一刻。父页面在 onMounted 里拿 canvasHost.value,很可能还是 null。QRCodeStyling.append(null) 不会抛错,只会什么都不画,于是表现成“内容有、参数有、就是没图”。

watch 一个模板 ref 并在回调里判断 el 是否存在,比在 onMounted 里加 nextTick 更稳:节点什么时候出现都能接住,不依赖猜测的渲染轮次。immediate: true 则覆盖“节点在监听建立前就已经存在”的情况。

同页的下载按钮也依赖这个实例。如果实例还没创建,按钮虽然可点,下载会没有反应。把“是否已挂载”与“内容是否为空”分开判断,能少一类“按钮没坏但没反应”的误报。

剪贴板与文件输入

解码页提供两条输入路径:文件选择和剪贴板粘贴。剪贴板走的是异步权限接口:

const items = await navigator.clipboard.read()
for (const item of items) {
  const type = item.types.find(value => value.startsWith('image/'))
  if (!type) continue
  const blob = await item.getType(type)
  await decodeFile(new File([blob], 'clipboard.png', { type }))
  return
}

它有三个现实限制:

  • 需要安全上下文(HTTPS 或 localhost);
  • 浏览器会弹权限提示,用户拒绝后要给出明确文案;
  • 剪贴板里可能同时有文本和图片,必须按 MIME 类型挑,不能假设第一项就是图。

文件选择器则是稳定兜底。decodeFile 先检查 file.type.startsWith('image/'),不是图片就提示格式问题;是图片但没扫到二维码,提示“没有识别到二维码”。两种失败分开报,用户才知道该换图还是换文件。

生成页还监听了 document 级粘贴事件,只在解码 Tab 激活时接管图片,并跳过输入框和可编辑区域,避免和文本框粘贴冲突。这类全局监听记得在卸载时移除,否则切页后仍会触发。

验证清单

输入预期
正相二维码(白底黑码)解出原文,链接类内容可点开
反相二维码(黑底白码)解出相同原文
4K 截图,二维码占画面很小缩放失败后由原图兜底解出
非图片文件提示图片格式错误
图片里没有二维码提示未识别到二维码
剪贴板权限被拒提示权限问题,文件选择仍可用
生成页首次进入预览区出现二维码,不是空白

解码结果如果是 WIFI: 开头的配置串,不要直接当链接打开。生成侧会对分号、逗号、冒号、反斜杠做转义,解码侧只负责还原文本。

FAQ

手机能扫、网页解不出,是库不行吗?

多数不是。先确认图片是否反相、二维码在画面里是否太小、解码前是否压缩过度。jsQR 对清晰的正相和反相图都能处理,失败通常出在输入像素上。

jsQR 已经尝试反相,还需要自己反相吗?

不需要。默认 attemptBoth 会先扫正相再扫反相。手动反相只会增加一次 Canvas 绘制和像素循环,除非你要控制扫描顺序或使用别的库。

图片缩小到多少合适?

以长边 1600 作为第一轮比较均衡;二维码在画面中占比很小时,不要只跑缩放图,失败后回原图。低于 800 的长边只适合二维码占满画面的情况。

深色背景的二维码怎么处理?

优先依赖库的反相扫描;如果库版本较旧不支援,再考虑手动反相。处理后仍失败,检查对比度是否足够、静区是否被裁掉。

解码结果是 WiFi 串,应该当链接打开吗?

不应该。WIFI: 是配置文本,不是 URL。界面只对 http:// 和 https:// 开头的内容提供跳转,其余按纯文本展示和复制。

结语

二维码解码的失败大多不在“识别算法”,而在输入准备:反相有没有被重复处理、缩放是否丢了模块、Canvas 是否真的挂上了。把这三件事分开验证,比反复换库更快。生成侧与解码侧的更多实现记录整理在 艺术二维码工具 和 前端开发 分类下。

评论

登录后即可参与评论

还没有评论,来说两句吧

相关文章