二维码失效的原因可以分成两大类：生成时的问题（尺寸、容错、颜色）和使用时的问题（打印质量、安静区、反光）。排查时按这两类逐步检查，通常能快速定位。
快速排查清单
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 的二维码依赖容错机制修复被遮挡的数据：
| 容错等级 | 可恢复损坏比例 | 推荐场景 |
|---|---|---|
| L | 7% | 环境干净、不加 logo |
| M | 15% | 通用场景 |
| Q | 25% | 有轻度干扰 |
| H | 30% | 加 logo、或有覆盖物 |
加 logo 时必须用 H 级容错，且 logo 面积不超过二维码面积的 25%。
不能遮挡的区域：三个角的定位方块（回字形图案）——这是扫码器找到二维码方向的关键，遮挡后无法识别。
原因 5：打印质量问题
打印引起的失效排查：
打印后扫不出 → 检查实际尺寸（小于 2.5 cm 先放大）
→ 肉眼看模块边缘是否清晰（模糊则换纸或提高 DPI）
→ 检查深色模块是否"扩张"粘连（换纸、降低墨水浓度）
→ 换白色背景纸张（彩色纸降低对比度）生成时注意：
- 提供 SVG 矢量图（任意尺寸打印无损）或至少 300 DPI 的 PNG（不要直接从屏幕截图缩放打印）
- 打印前在软件里预览一下模块是否清晰可辨