A. 痛点描述（Problem）#
二维码“扫不出来”通常不是随机事件，而是可解释、可复现的工程问题：
- 你拿到一张二维码图，但扫码 App 一直转圈
- 同一张码，有的手机能扫，有的扫不出
- 线上投放后发现部分用户无法识别，排查成本极高
这篇文章给你一套排错路径：先判断二维码内容是否可被解析，再逐项排查影响识别率的因素。
工具入口：二维码生成与解析
👉 立即使用：二维码生成与解析
B. 核心原理（Deep Dive）——解码失败通常发生在哪一步？#
二维码识别大致分三步：
- 定位：找到二维码的位置与三个定位角
- 采样：按模块网格采样黑白信息
- 纠错与解码：恢复数据并输出文本/URL
因此失败原因也高度集中在：
- 定位失败（留白不足、背景干扰、反光、倾斜过大）
- 采样失败（模糊、分辨率不足、压缩造成边缘糊）
- 纠错失败（遮挡过大、污渍/Logo 覆盖、对比度不足）
C. 操作指南（Step-by-step）——先用工具确认“这张图到底能不能解”#
第一步：切到“解码”页，上传二维码图片#
建议优先使用：
- 原始 PNG
- 或高清截图（避免社交软件二次压缩）
如果工具能解析出内容，说明二维码本身可读；如果工具也无法解析，问题大概率在图片质量或二维码生成参数。
第二步：解析成功后做“内容校验”#
常见内容类型：
- URL（检查是否完整、是否被截断）
- 文本（检查是否包含不可见字符）
如果内容是 URL，建议再用 URL 编解码工具确认是否存在二次编码：
立即使用：URL 编解码
D. 高频失败原因与修复策略（按发生概率排序）#
1）图片被压缩或过度缩放（边缘糊）#
表现：
- 手机上的预览看起来没问题，但扫码失败
- 工具解析偶尔成功、偶尔失败
修复：
- 使用原图 PNG 下载投放，不要走二次截图链路
- 提高二维码分辨率或模块大小
2）留白（quiet zone）被裁掉#
表现：
- 二维码紧贴边缘或被 UI 圆角裁切
- 定位角不完整
修复：
- 生成时增加留白
- 前端展示时避免
overflow: hidden把留白裁掉
3）对比度不足（浅色码/复杂底图）#
表现：
- 某些机型能扫，某些机型不行（不同算法对对比度敏感度不同）
修复：
- 深色前景 + 浅色背景
- 避免渐变与纹理背景
4）反光、屏幕摩尔纹、倾斜角过大#
修复：
- 增大二维码尺寸
- 打印物使用哑光材质或避免强反光区域
5）Logo 遮挡过大（纠错扛不住）#
修复：
- 提高纠错等级到 Q/H
- 缩小 Logo 或给 Logo 加白底边框
- 不要遮挡定位角与靠近定位角的大块区域
6）内容过长导致码过密#
表现：
- 生成出来“像马赛克”，模块极密
修复：
- 采用短链
- 只存必要信息，把复杂数据放服务器，通过 URL 引用
7）同一画面有多个二维码（或有类似方块图案干扰）#
修复：
- 单画面尽量只放一个二维码
- 放多个时拉开距离，并用明显提示引导用户对准目标码
E. 常见问题（FAQ）#
1）为什么工具能解码，但扫码 App 扫不出来？#
可能是扫码 App 对定位/对比度更敏感。建议提升二维码尺寸、对比度与留白，尤其是投放到打印物或弱光场景时。
2）二维码内容是 URL，但打开后不对？#
常见原因是链接被截断、被二次编码、或投放平台做了跳转改写。建议用工具先读出原始 URL，再用浏览器直接打开验证。
3）二维码能不能放敏感信息？#
不建议。二维码内容通常是明文可读，任何人都能解析。敏感信息应当放在服务端，用短期有效的 token 或一次性链接承载。
工具推荐#
- 二维码生成与解析：立即使用：二维码生成与解析
- URL 编解码（检查二次编码）：立即使用：URL 编解码