一、先纠正一个误解：二维码只是"换一种画法"

二维码不包含任何加密。它把文字换成图形，任何扫码工具都能把内容原样读出来，甚至不用扫——普通的解码软件也能还原。所以这条边界必须记牢：

不要用二维码存放密码、身份证号、银行卡号。包括"把 WiFi 密码做成二维码贴在店里"这种做法，等于把密码公开给所有路过的人。

确实需要保密时，正确顺序是：先用带密码的工具或加密方式处理内容，再生成二维码；而不是指望二维码本身提供保护。

二、容量：40 个版本，越"高级"装得越少

二维码共有 40 个版本，版本越高格子越密：版本 1 是 21×21 个模块，版本 40 是 177×177 个模块，容量随之增加。但这里有个反直觉的取舍——

纠错等级分四档：L 约 7%、M 约 15%（默认）、Q 约 25%、H 约 30% 可恢复。等级越高越抗污损、被遮挡也能读，但用来"备份"的格子越多，留给正文的就越少。内容多到装不下时，生成工具会提示你降低等级或缩短内容，这不是软件偷懒，而是数学上的硬限制。

三、静默区：那圈"没用的白边"决定成败

规范要求码点区域四周各留至少 4 个模块宽度的空白，这块空白叫静默区。它一点也不浪费：扫码器先靠这圈空白判断"哪里是二维码的边界"，再去做定位与采样。静默区被切掉或压窄，扫码器找不到边界，识别直接失败。

很多"贴在墙上的二维码扫不出来"，就是把图裁到了码点边缘，或排版时被旁边的文字压住了一圈。改回 4 个模块的空白，往往立刻恢复。

四、对比度：不是好不好看，是能不能二值化

扫码器的工作流程是先转灰度、再按阈值判黑判白。前景与背景的亮度差越大，二值化越干净；反差太小（浅灰码点配白底、深蓝配深灰），会有一批模块被判成"灰"而丢失，读不出来。

五、尺寸：印在小卡片上，像素不是越大越好

导出 PNG 的边长可在 128 到 1024 像素之间设。听起来越大越好，但印在小卡片上，太密的图反而扫不出来——一般 300 到 600 像素够用。关键不是像素数，而是印刷后的实际尺寸与扫码距离匹配。

另外提醒一句：内容里带 URL 时加上 https://，手机才知道该用浏览器打开；WiFi 二维码里如果名称或密码含有 \ ; , : " 这些字符，需要自动加反斜杠转义——这正是很多工具生成的 WiFi 码扫不出来的原因。

最后一层是隐私：把内容提交给服务器生成，意味着你的 WiFi 密码、手机号、地址经过了别人的机器，还可能被记录。二维码的生成本身不需要后端，能本地完成就别上传。