二维码失效的原因可以分成两大类：生成时的问题（尺寸、容错、颜色）和使用时的问题（打印质量、安静区、反光）。排查时按这两类逐步检查，通常能快速定位。
快速排查清单
1. 三个角的定位方块（回字形）完整且清晰？
2. 码模块和背景颜色对比度是否足够？
3. 四周是否有足够的空白安静区？
4. 打印尺寸是否大于 2.5 cm × 2.5 cm？
5. 如果有 logo，是否使用了 H 级容错？
6. 用微信 / 支付宝 / 系统相机分别测试——哪个能扫？
原因 1：安静区不足
安静区（Quiet Zone）是二维码四周必须保留的空白区域，最小宽度为 4 个模块单元——即构成二维码最小格子的尺寸。
错误（安静区为 0）：
┌────────────────────┐
│ 文字二维码文字文字 │
└────────────────────┘
正确（四周留白）：
┌──────────────────────────────┐
│ │
│ ┌──────────────────┐ │
│ │ 二 维 码 │ │
│ └──────────────────┘ │
│ │
└──────────────────────────────┘
安静区不足的典型场景：
二维码直接贴在图片边缘或文字旁边
多个二维码紧密排列
有装饰性外框但紧贴码模块边界
修复：在生成工具里设置边距（margin），通常 10–20 px；打印时保证二维码周围有 3–5 mm 空白。
原因 2：尺寸太小
使用场景最小尺寸建议手机近距离扫（30 cm 以内）2 cm × 2 cm桌面展示、名片3 cm × 3 cm海报展示（1 m 距离）8 cm × 8 cm户外广告（3 m 距离）30 cm × 30 cm
数据量影响尺寸：二维码存的信息越多，版本越高，模块越密。同样物理尺寸下，信息越多越难扫。
优化方向：
用短链接代替原始 URL（从 100 字符压缩到 20 字符）
避免在二维码里直接存储大段文字
原因 3：对比度问题
扫码器通过深浅对比识别码模块，对比度低于阈值时识别失败。
安全的颜色搭配：
码模块颜色背景颜色是否安全黑色白色✅ 最安全深蓝 / 深绿 / 深红白色 / 浅色✅ 安全黑色浅黄 / 浅绿✅ 安全浅灰白色❌ 对比度不足彩色渐变白色❌ 部分区域失效深色深色❌ 无法识别
反色二维码（白码黑底）：大多数现代扫码器支持，但兼容性不如正色，建议测试后再用。
原因 4：logo 遮挡超出容错上限
带 logo 的二维码依赖容错机制修复被遮挡的数据：
容错等级可恢复损坏比例推荐场景L7%环境干净、不加 logoM15%通用场景Q25%有轻度干扰H30%加 logo、或有覆盖物
加 logo 时必须用 H 级容错，且 logo 面积不超过二维码面积的 25%。
不能遮挡的区域：三个角的定位方块（回字形图案）——这是扫码器找到二维码方向的关键，遮挡后无法识别。
原因 5：打印质量问题
打印引起的失效排查：
打印后扫不出 → 检查实际尺寸（小于 2.5 cm 先放大）
→ 肉眼看模块边缘是否清晰（模糊则换纸或提高 DPI）
→ 检查深色模块是否"扩张"粘连（换纸、降低墨水浓度）
→ 换白色背景纸张（彩色纸降低对比度）
生成时注意：
提供 SVG 矢量图（任意尺寸打印无损）或至少 300 DPI 的 PNG（不要直接从屏幕截图缩放打印）
打印前在软件里预览一下模块是否清晰可辨
配套工具
二维码生成 — 生成时选择容错等级和导出分辨率
二维码批量生成 — 批量生成后抽样测试扫码
图片压缩 — 高分辨率二维码图片体积太大时压缩