二维码生成了却扫不出来：内容、留白、对比度和截图质量怎么排查

二维码生成了却扫不出来，先区分两件事：扫描器是否“看不懂这张图”，以及扫描后得到的内容是否“不能使用”。前者查留白、对比度、尺寸和压缩，后者查网址、文本或业务参数本身。

最省时间的验收方式是用二维码与条形码工具重新生成，然后把下载的最终图片再拖回识别区。不要只扫编辑器里的预览，因为真正发布的文件可能已经被截图、裁切或平台压缩。

第一步：先验证内容，不要先修图片

二维码被识别后，可能出现三种结果：

• 返回的文本与原始输入一致，而且内容可用；
• 能识别，但网址打不开、参数缺失或文本不是预期值；
• 完全无法识别。

第二种属于内容问题。把网址直接粘进浏览器，检查协议、域名、路径和查询参数；文本则逐字核对空格、换行和特殊字符。重新美化二维码不会修复一个本来就无效的网址。

图叮当前二维码输入按 UTF-8 字节计算，超过 2953 字节会提示内容过长。中文通常占用的字节多于英文字符，因此“字符数看起来不多”不等于二维码内容很短。

第二步：保住四周留白

二维码四周的空白区域用于帮助识别器确定边界。最常见的破坏方式不是生成器本身，而是后续处理：

• 截图时紧贴黑色码点裁切；
• 给二维码加边框、标题或贴纸，元素离码点太近；
• 放进海报后被其他图形压住；
• 导出时只保留中间主体，裁掉外围空白。

图叮当前生成器会带留白生成最终图片。下载后不要再次“自动裁边”；如果必须放进版式，给二维码单独留一块干净背景。

图注：先核对解码内容，再检查最终文件的留白、对比度和尺寸。

第三步：检查真实对比度

深色码点配浅色背景最稳。问题常出在“设计稿里能看见，摄像头里分不开”：

• 浅灰码点放在白底上；
• 黑色区域叠了透明度，落到复杂背景后变灰；
• 渐变穿过定位图形；
• 深色背景上仍使用深色码点；
• 屏幕反光、打印褪色或纸张纹理降低局部对比度。

不要只看中心区域。三个角上的定位图形、最外圈码点和背景都要清楚。需要品牌色时，先生成普通高对比版本做基线，再逐步改色并每次反向识别。

第四步：尺寸不是只看像素宽度

同样是 300px 的二维码，内容越长，内部码点越密，每个模块得到的像素越少。再经过聊天软件缩略图或网页 CSS 缩放，细小模块容易糊在一起。

排查时不要照搬一个“万能最小尺寸”，而要在真实场景测试：

1. 用最终内容生成，不拿短测试网址代替；
2. 放到最终海报、网页或标签的实际显示尺寸；
3. 从预期距离，用至少两台不同手机识别；
4. 打印场景再测真实纸张和打印机；
5. 识别不稳时，优先缩短内容或增大二维码显示面积。

如果长网址带大量追踪参数，可以先确认是否确实需要全部保留。缩短内容能降低码点密度，但短链接必须来自你信任且可长期维护的域名，不能为了好扫引入失效跳转。

第五步：避免截图、拉伸和二次压缩

生成器下载的原文件通常比截图更可靠。截图可能带来非整数缩放、系统锐化、屏幕像素纹理或裁边；在编辑器里拖动四角时取消比例约束，还会把正方形拉成长方形。

发布链路也可能再次处理图片：

• 聊天软件生成低清预览；
• 内容平台转成有损格式；
• CMS 自动缩略；
• 文档软件在导出 PDF 时重采样；
• 打印驱动为了适配页面再次缩放。

因此，反向识别要针对“最后一次处理后的文件”，不是生成器刚输出的原图。原图能扫、平台下载图不能扫，就沿平台处理链排查，不要反复生成相同内容。

第六步：换设备前先做交叉验证

摄像头脏污、对焦距离、弱光和识别软件差异确实会影响结果，但它们不应成为第一解释。可以用以下矩阵快速定位：

测试结果	更可能的问题
所有设备都扫不出原文件	内容密度、留白、对比度或图像损坏
原文件能扫，海报或截图不能	版式裁切、缩放或二次压缩
一台设备不能扫，其他设备正常	对焦、光线、识别应用或设备兼容
能识别但打开失败	二维码内容或目标服务

最终交付前，保留一份下载原图和一份实际发布文件，同时把后者重新上传到二维码识别入口核对返回文本。二维码的完成标准不是“画面上出现黑白方块”，而是最终文件在真实尺寸、真实设备和真实内容下都能稳定解码。