二维码扫不出来怎么办：纠错级别、模块尺寸与印刷的硬约束

约 7 分钟读完 · 更新于 2026-10-21 · 文中每条都能在下面的配套工具里动手验证

结论先行：扫不出只有四类原因

排查按这个顺序，两分钟能定位。第一，尺寸：模块小于约 2 像素，扫码器或手机根本采样不到有效信息，尤其是屏幕截图后又被压缩过。第二，对比度：浅灰底配深灰码、深色底配深色码都会让自动曝光后的二值化失败，浅底深码最稳。第三，纠错级别：盖了 logo、贴了胶带、被折了一道，错误率超过 L 级（7%）就废了。第四，容量：内容超出所选版本能容纳的字节数，码根本画不出来或画出残缺矩阵。所以生成时不要把这些交给运气，参数一次给对。

纠错级别 L / M / Q / H 分别能盖住多少

容量与版本：内容越长，码越大

二维码有 1-40 共 40 个版本，版本越高模块越多、容量越大，边长按 4(n+17) 模块增长，n 为版本号。粗略换算：字节模式（任意内容，UTF-8 中文按每字 3 字节）从版本 1 的 17 字节到版本 40 的 2953 字节；纯数字最省，版本 1 可放 41 位，版本 40 可放 7089 位；大写字母加数字的字母数字模式介于两者之间，同版本约 25 到 4296 个字符。升一级版本不只是「大一点」——纠错级别和模式都会改变每模块承载的位数，所以先把内容压短，再谈尺寸。URL 里带一串查询参数往往比换更高版本更有效。

尺寸与印刷的硬约束

const fs = require("fs");
const QR = require("qrcode");

// 每行一个标识；二维码只放短内容，详情放落地页
const codes = fs.readFileSync("assets.csv", "utf8")
  .trim().split("\n").slice(1)
  .map(r => r.split(",")[0]);

(async () => {
  for (const id of codes) {
    // 贴到设备上会脏，用 Q 起步；带 logo 直接上 H
    await QR.toFile(`out/${id}.png`, `https://s.example.com/d/${id}`, {
      errorCorrectionLevel: "Q",
      width: 512,          // 输出像素，务必是模块尺寸的整数倍
      margin: 4,           // 静区：约等于 4 个模块，缺了容易扫不出
      color: { dark: "#000000ff", light: "#ffffffff" },
    });
  }
})();

1. 把导出的 PNG 拖进解码工具，看能否读回原始 URL
2. 用另一台手机实测，而不是同一台（同一台的解码库可能"将就"）
3. 打印一张实物再扫，油墨和覆膜的影响只有实物能测出来
4. 别用微信内置的"扫一扫"当唯一验收标准，它的容错策略偏保守

二维码和条形码怎么选

区别不只是长得不一样。二维码是二维矩阵，容量从几十字节到近 3KB，能存网址、JSON、汉字甚至一段短文本，读取靠手机摄像头，允许 360 度旋转但需要足够的模块尺寸；条形码是一维黑白条，容量通常几十个字符，读取靠激光扫描枪，速度快、允许从任意角度扫，对印刷质量更宽容。所以选型按场景：商品零售、图书馆、仓库这类已有扫码枪流程的用 EAN-13 / UPC / CODE128；需要手机直接扫、需要存 URL 或中文的用二维码；需要手机和扫码枪都能读、又不想换硬件的，条形码更稳。混合方案也常见：外箱印一维条码做物流分拣，内侧印二维码做溯源详情。

二维码中间能加 logo 吗

• 可以，但要用 H 级（30% 容错）并把 logo 面积控制在总面积的 25% 以内。
• logo 必须是正方形、四边留出完整的定位图案（三个角上的方块），别压住它们。
• logo 背景要与模块颜色一致，不要用渐变或半透明，边缘留一圈白色更稳。
• 内容越长，同样的 logo 占比对应的实际遮挡越严重——长内容建议去掉 logo。

嵌入页面与压缩

页面里最省事的是把 PNG 转成 Base64 data URI 直接内联，省掉一次请求，但要清楚代价：Base64 会让体积增加约三分之一，所以务必先压缩到刚好够扫的尺寸再编码——二维码是纯黑白图形，用调色板化或质量 60 左右的 WebP/JPEG 通常还能再省一半。大量二维码（几百张以上）不要内联，改用打包下载。批量场景记得固定三个参数：纠错级别、模块尺寸、静区，参数不统一会让后续替换某一张时扫不出来的投诉无从复现。

常见问题