做个线下活动报名，需要在物料上印一个扫码入口，或者在后台给每个订单生成一张带二维码的核销单。这两种需求都不适合引一个几 MB 的前端库，用二维码生成 API 更快。

两种接口形态

第一种是直接返回图片，请求地址里带上内容，响应就是 png 或 svg：

https://api.example.com/qr?text=https%3A%2F%2Fexample.com%2Fjoin&size=300&margin=10

第二种是返回 JSON，里面给图片的 base64 或者一个临时下载地址。前一种适合直接 img 引用，后一种适合需要控制存储的场景。

参数里最该关注的几项

  • text / data：二维码承载的内容，URL 记得先编码，否则参数里的问号会把后面的参数吃掉。
  • size：边长像素。线下印刷至少要 200 以上，太小扫码识别率会掉。
  • margin：四周留白，也就是静区。规范要求至少 4 个模块宽，留白不够时扫码器经常识别不出来。
  • level / ecc：容错等级，L、M、Q、H 四档。印刷品建议用到 Q，表面有污渍也不容易失败。
  • format：png 还是 svg。做印刷物料优先用 svg，放大不失真。

容错等级怎么选

二维码的纠错原理是插入冗余数据，等级越高，同样的内容需要的模块越多，二维码也更密。L 约 7% 容错，M 约 15%，Q 约 25%，H 约 30%。

内容很短时用 H 完全没问题，还能在中间叠 logo。内容长的时候用 H 会让二维码变得非常密，小尺寸打印出来反而更难扫。经验做法是：网址类内容用 M 或 Q，长文本用 L。

几个容易出错的地方

第一，中文乱码。接口一般按 UTF-8 编码，但部分老扫码器按 GBK 解析，出来的就是乱码。如果内容里有中文，测试时用两三种不同品牌的手机都扫一遍。

第二，URL 太长。一般是短链接更好，二维码模块越少越容易识别，尤其是印在小尺寸的卡片上。

第三，缓存。同一段内容生成的图片被 CDN 缓存住了，改了内容却还是旧码，记得在 URL 里加版本参数。

自己生成还是调接口

如果用 Node，qrcode 这个库几行就能出图，不需要联网，也不用担心服务方限流。用后端语言生成还有个好处：可以把 logo 合成进二维码。只有在前端批量出图、或者需要在线预览这类场景，调 API 才更省事。

最后提醒一句，二维码能承载的只是文本，不要拿它当安全凭证。核销码最好是一次性的，并且在服务端校验签名，防止有人截个码反复使用。