上周帮一个做零售的朋友收拾他们小程序的线下推广链路本来以为半小时能搞定的事硬是从下午两点折腾到晚上八点。问题不在代码有多难写而在一堆没人提前告诉你的细节码的尺寸给多少才不糊、scene 参数到底能塞进去多少字节、接口返回的二进制流被当成 JSON 解析后报了个语焉不详的错、图片存哪儿后续才不会被缓存坑到。这类活儿单看文档每一行都懂串起来跑一遍才知道哪里会漏水。这篇就把小程序太阳码与二维码生成的整条链路摊开讲从三种码的选型差异到调用凭证的获取与缓存到生成接口的参数拆解再到二进制流的落盘与对象存储、CDN 分发最后是批量生成时的限频与容错。适合两类人看——一类是刚接手小程序推广需求、还没搞清楚太阳码和二维码区别的后端或全栈开发另一类是已经在写、但生成出来的图不是扫不出来就是线上 404 的同学。我会把每一步为什么这么选讲清楚而不是甩一段代码让你自己悟。1. 三种码先分清楚选型错了后面全白干1.1 太阳码、普通二维码、带参二维码到底差在哪很多人第一次听到太阳码这个词会愣一下其实就是小程序码的俗称——因为它是圆形的中间嵌着小程序图标四周的码点呈放射状铺开看起来像一轮太阳。从视觉上它比方形二维码好看从技术上讲它承载的信息结构和普通二维码也不是一回事。普通二维码本质是一段字符串的二维编码扫码工具解析出一串 URL浏览器打开就是网页。小程序码则是由平台服务端直接渲染出的图像里面编码的是进入哪个小程序、打开哪个页面、带什么参数必须由对应的小程序客户端识别。这两者的生成路径完全不同前者你可以用任意开源库在本地离线生成后者必须调用平台的服务端接口因为渲染算法和校验逻辑都在平台侧。还有一类容易被混淆的带参二维码是小程序平台早期提供的方形码接口。它现在依然可用但官方更推荐用小程序码原因是方形码在样式定制上限制更多且部分场景下的识别率不如圆形码。我整理了一张对照表选型的时候直接对号入座即可。维度小程序码太阳码带参二维码普通二维码形状圆形放射状方形方形生成方式服务端接口服务端接口本地库离线生成能否带参数能scene 字段能scene 字段能拼在 URL 里参数容量32 个可见字符32 个可见字符基本不受限样式定制支持透明底、线条色支持线条色完全自由识别端仅对应小程序客户端仅对应小程序客户端任意扫码工具看这张表有个关键点如果你的码是印在户外广告牌上、希望路人用系统相机扫一下就能跳转那必须用小程序码或带参二维码因为系统相机识别后会唤起对应的小程序。如果你生成的是普通二维码扫出来就是一串 URL用户还得再多点一步。这一步的流失率在投放场景里往往高得吓人。1.2 场景对号入座什么时候非它不可我在实际项目里遇到的场景大致分四类选型逻辑差别挺大。第一类是线下物料比如门店台卡、包装盒、宣传单页。这类场景的核心诉求是印刷清晰、识别率高、视觉上和品牌调性匹配。太阳码在这里优势明显圆形的构图放 LOGO 更好看而且支持透明底设计师能直接叠在背景图上。第二类是分享裂变用户 A 分享给用户 BB 扫码进来后要能识别出是 A 带来的。这类必须带参数而且参数里通常塞的是邀请码或者短链 ID。注意这里是 32 个字符的硬约束后面会专门讲怎么压缩。第三类是一物一码比如每个商品包装上印一个唯一的码扫码后进入该商品的详情页或验证页。这类场景数量级大动辄几十万上百万张对批量生成的稳定性和存储成本极其敏感。第四类是内部测试开发阶段自己生成几张码贴到测试群里。这类反而最容易出问题因为很多人不知道开发版和正式版的页面路径处理逻辑不一样生成出来的码扫了打不开白白怀疑人生。提醒一句如果你的需求只是让用户扫一下打开某个网页压根不需要小程序码普通二维码配上你的落地页链接就够了。我见过有团队为了一个纯 H5 活动页去接小程序码接口纯属把简单问题复杂化。1.3 参数容量红线32 个字符是怎么压死人的这是最容易踩的坑没有之一。小程序码的 scene 参数上限是 32 个可见字符注意是可见字符不是字节。这个限制背后有它的道理码的图案容量是固定的塞太多信息会导致码点密度过高印刷稍有偏差就识别不了。32 个字符能装什么装一个 UUID 是 36 位刚好超了。装一个自增 ID 绰绰有余但你得考虑安全性——直接把数据库主键暴露在码里别人拿到码就能推测你的业务量。装一个短链 code 是常见做法比如 8 位 Base62 字符空间是 62 的 8 次方约 218 万亿够用了。我一般的处理是生成一个 8 到 10 位的短码服务端维护短码到业务参数的映射表。用户扫码进入小程序后onLoad里拿到 scene先请求一次你自己的接口换回完整参数再渲染页面。多一次请求换来的是参数容量的彻底解放和安全性的提升。还有个细节scene 里不要放、、?、#这类字符。虽然接口层面不一定会报错但在部分客户端版本上解析会出偏差。我用的是 Base62 字符集0-9a-zA-Z完美避开所有特殊字符省心。如果你实在想放中文务必在服务端做一次 URL 编码再传客户端拿到的会是编码后的串需要decodeURIComponent一次才能还原。2. 调用凭证与接口权限真正卡住新人的地方2.1 access_token 的获取、缓存与刷新窗口生成小程序码的所有接口都需要一个调用凭证行业里通常叫 access_token。这东西有两个特性决定了它必须被认真对待一是有效期固定为 7200 秒二是重新获取会导致旧凭证失效。第二条是关键。我见过太多项目在每次请求生成接口前都去调一次获取凭证的接口本地测试一切正常一上线压测就开始随机报凭证失效。原因是多台机器同时刷新A 机器拿到的新 token 把 B 机器手上的旧 token 顶掉了B 的请求自然失败。正确的做法是把凭证集中管理。小项目用单机内存加锁就够了多实例部署必须放到共享存储里比如缓存服务或数据库。核心逻辑是读取缓存不存在或剩余有效期小于 5 分钟才去刷新刷新时加分布式锁防止并发重复刷新。// 伪代码带锁的凭证管理 async function getAccessToken() { const cached await cache.get(TOKEN_KEY); if (cached cached.expireAt - Date.now() 5 * 60 * 1000) { return cached.value; } const lock await cache.acquireLock(LOCK_KEY, 10); if (!lock) { await sleep(200); return getAccessToken(); } try { const data await requestTokenFromPlatform(); const ttl (data.expires_in - 300) * 1000; await cache.set(TOKEN_KEY, { value: data.access_token, expireAt: Date.now() ttl }, ttl); return data.access_token; } finally { await cache.releaseLock(LOCK_KEY); } }留 5 分钟余量是经验值。太短了刷新过于频繁可能撞上平台的调用频率限制太长了遇到平台侧主动让凭证失效的情况比如密钥重置你的服务会在余量窗口内一直用着废凭证。5 分钟在绝大多数场景下都比较稳。2.2 谁有权限调用账号类型与接口开通这块是纯粹的文档里有但你不一定会看的部分。生成小程序码的接口对账号类型有要求个人主体和部分未认证的账号是调不了的会直接返回权限相关的错误码。另外某些接口需要在后台单独申请开通不是拿到密钥就能用。还有一个更隐蔽的点page字段填的页面路径必须在已发布版本里存在。开发阶段你本地加了个新页面还没提交审核也没发布就去生成码接口会返回路径不存在的错误。这时候有个check_path参数可以临时关掉校验但记住这只是让生成动作成功用户扫码后依然打不开那个页面别自欺欺人。我的建议是项目启动阶段就先用命令行把凭证获取和一次最简单的码生成跑通确认账号权限没问题再动手写业务代码。这一小时的验证能省掉后面半天的排查。2.3 先用命令行跑通再动手写业务代码这条经验我逢人就讲。凡是对接外部服务先用最裸的方式把接口调通再去套你项目里的封装层。因为一旦封装层出问题你根本分不清是自己的代码错了还是接口返回了错误。# 第一步拿凭证域名按平台文档填写 curl -s https://${API_HOST}/cgi-bin/token?grant_typeclient_credentialappid${APPID}secret${SECRET} # 第二步生成码把二进制流直接存成文件 curl -s -X POST https://${API_HOST}/wxa/getwxacodeunlimit?access_token${TOKEN} \ -H Content-Type: application/json \ -d {scene:a1b2c3d4,page:pages/index/index,width:430} \ -o code.png # 第三步验证拿到的到底是不是图片 file code.png第三步的file命令特别重要。如果输出是PNG image data说明成功如果输出是JSON data把那文件cat出来里面就是错误码。很多人省了这一步直接双击打开发现是乱码或打不开然后开始怀疑网络。3. 生成环节的参数拆解与代码落地3.1 三套接口的适用边界平台提供的码生成接口不止一个名字相近但用途不同混用会浪费大量时间。第一个是有限制接口特点是数量有上限默认十万个生成后永久有效页面路径和参数都不能太长。它适合生成量小、且码可以长期复用的场景比如你只有几十个渠道每个渠道一张固定码。缺点是数量用完了要么等配额恢复要么加钱。第二个是无限制接口名字里就带着 unlimit数量上不限但 scene 参数限制在 32 个可见字符。这是绝大多数项目的首选尤其是一物一码、动态渠道码这类场景。第三个是二维码接口生成的是方形码能力上和无限制接口接近但样式定制项少一些。只有在你明确需要方形码比如某些印刷物料已有方形开孔时才用它。选型上我的默认建议很简单能用无限制接口就用无限制接口。它兼顾了数量和灵活性除非你有特殊的样式要求否则没必要碰另外两个。3.2 请求体逐字段解释page、scene、width、auto_color、line_color、is_hyaline参数表看着简单但每个字段背后都有实际影响我逐个说。page是扫码后打开的页面路径格式是pages/xxx/xxx开头不带斜杠可以带查询参数。这里有个细节带查询参数时参数值需要做 URL 编码否则遇到特殊字符会被截断。另外页面的层级不要太深我遇到过路径过长导致生成的码图案异常的情况虽然不常见但排起来很费劲。scene就是前面反复强调的 32 字符参数。这里再补一句不同接口对 scene 的限制不完全一样有的接口允许部分特殊字符有的严格只允许可见字符。统一按最严格的标准来写代码永远不会出错。width是码的边长单位像素范围 280 到 1280。这个值直接决定了印刷质量。经验公式是印刷物理尺寸英寸× 300 DPI 需要的像素数。比如你要印一个 3 厘米见方的码约 1.18 英寸需要约 355 像素。实际上考虑到码点清晰度我一般会翻倍取 430 或 500。取太小印出来糊成一片取太大文件体积上去了但清晰度收益递减还白白多花存储和流量。auto_color控制是否自动配色默认 false。设成 true 时平台会根据码的内容自动选择颜色但实际效果不太可控我不建议开。line_color是线条颜色只在auto_color为 false 时生效传 RGB 对象。品牌色需要用的话在这里指定注意颜色和背景的对比度要够浅色码在深色背景上识别率会崩。is_hyaline控制是否生成透明底默认 false。这个参数对设计师很友好透明底可以直接叠在任意背景图上。但有个坑透明底 PNG 在某些老旧打印机上渲染会出现黑底印刷前务必先打样确认。check_path前面提过了开发阶段可以关生产环境一定要开避免生成一堆扫不开的死码。3.3 响应是二进制流别拿 JSON 解析器怼这是新人最高频的错误。生成成功时接口返回的是图片的二进制数据响应头里的Content-Type是image/png或image/jpeg。生成失败时返回的却是 JSON 格式的错误体。问题在于如果你用了一个默认按 JSON 解析的 HTTP 客户端成功的情况反而会报解析错误如果你按二进制接收失败的情况你就拿到了一段二进制内容直接存成.png文件打开一看是乱码。正确姿势是按二进制接收然后检查响应头的 Content-Type。如果是 JSON把二进制转成字符串解析出错误码否则就是图片直接落盘或者上传。const axios require(axios); async function generateSunCode(token, { scene, page, width 430 }) { const res await axios.post( https://${process.env.API_HOST}/wxa/getwxacodeunlimit, { scene, page, width, auto_color: false, line_color: { r: 0, g: 0, b: 0 }, is_hyaline: false, check_path: true, }, { params: { access_token: token }, responseType: arraybuffer, // 关键按二进制接收 timeout: 15000, } ); const contentType res.headers[content-type] || ; if (contentType.includes(application/json)) { const err JSON.parse(Buffer.from(res.data).toString(utf8)); throw new Error(码生成失败 errcode${err.errcode} errmsg${err.errmsg}); } return Buffer.from(res.data); }Python 版本同理用requests的时候不要加.json()直接取response.content先看Content-Type再决定怎么处理。import requests def generate_sun_code(token, scene, page, width430, api_hostNone): url fhttps://{api_host}/wxa/getwxacodeunlimit payload { scene: scene, page: page, width: width, auto_color: False, line_color: {r: 0, g: 0, b: 0}, is_hyaline: False, check_path: True, } resp requests.post( url, params{access_token: token}, jsonpayload, timeout15, ) ctype resp.headers.get(Content-Type, ) if ctype.startswith(application/json): info resp.json() raise RuntimeError(fgenerate failed: {info}) return resp.content另外补一条图片格式是 JPEG 还是 PNG 取决于参数组合is_hyaline为 true 时必然是 PNG因为 JPEG 不支持透明。如果你的代码里硬编码了.jpg后缀而实际拿到的是 PNG某些浏览器仍能显示靠嗅探但下载下来用图片软件打开会报错。稳妥做法是从响应头里取 MIME映射到后缀。4. 存储方案从临时文件到可长期分发的 URL4.1 为什么不建议把图片塞进数据库我见过把图片二进制直接存进数据库 blob 字段的项目理由通常是省事不用再接一套存储。短期确实省事长期全是麻烦数据库体积膨胀、备份恢复变慢、查询时不小心select *就把几十兆图片捞出来了、主从同步延迟被放大。码图片是典型的静态资源生成后基本不变天然适合放对象存储。数据库里只存一个 URL 或者对象 key 就够了轻量、可索引、可迁移。如果你的量非常小比如几百张直接存本地磁盘加个静态文件服务也能跑。但要注意几点一是容器化部署时本地磁盘是临时的重启就没了二是多实例部署时各机器上的文件不一致用户可能一会儿能访问一会儿 404三是要自己处理备份。所以只要不是单机玩具项目我都建议直接上对象存储。4.2 对象存储 CDN 的组合与命名幂等对象存储解决了存哪儿CDN 解决了快不快。码图片的特点是访问集中在扫码瞬间且同一张码可能被成千上万人扫完美契合 CDN 的缓存模型。命名策略上我推荐用业务维度 内容哈希的组合而不是纯随机。比如suncode/{appid}/{sceneHash}.pngsceneHash是 scene 参数经过哈希后的十六进制串取前 16 位即可。这样同一个 scene 重复生成时会覆盖到同一个 key天然幂等不会因为重试产生一堆重复文件。同时哈希之后即使 key 泄露也无法反推原始参数。如果同一个 scene 需要支持不同尺寸比如线上用 430印刷用 1280就把尺寸也拼进 keysuncode/{appid}/{sceneHash}_{width}.png。别想着存一份大图然后动态缩码这种图形缩放后码点会糊必须按目标尺寸重新生成。4.3 私有桶还是公共读一个容易忽略的坑对象存储的桶一般有公共读和私有两种权限。公共读的桶任何人拿到 URL 就能访问配置简单配合 CDN 也顺畅。私有桶需要签名 URL安全性高但每个 URL 都有有效期不适合长期印在物料上的码。我的判断标准是这张码本身有没有敏感信息。如果 scene 里是哈希后的短码本身不泄露业务数据那公共读完全没问题反而省掉签名计算的开销和过期风险。如果 scene 里直接放了用户 ID 之类的信息不推荐但确实有人这么干那就要么改设计要么走私有桶加签名。还有个实际的坑私有桶配 CDN 时CDN 回源需要带上签名配置复杂度会明显上升而且签名过期后 CDN 缓存的旧内容可能还在导致行为不一致。这种问题排查起来非常耗时所以能公共读就公共读把敏感信息挡在 scene 设计阶段。5. 批量生成限频、队列与容错设计5.1 频率限制怎么算单张生成是几百毫秒的事但一旦上量比如给十万个商品各生成一张码同步循环调接口必然撞墙。平台对这类接口有调用频率限制超了会直接返回频率相关的错误码。计算需求很简单十万张假设你稳定跑到每秒 20 次调用需要 5000 秒约 1.4 小时。这个数字要先算出来再跟业务方确认能不能接受。如果不能接受那要么申请提额要么错峰分批要么就在业务上做妥协——比如先只给 Top 一万的商品生成码。我在项目里一般会把批量任务做成异步作业接口收到请求后立刻返回一个任务 ID后台队列慢慢跑前端通过轮询或推送拿进度。这样即使跑两小时用户也不会看到一个转圈的页面等到崩溃。5.2 队列 幂等的落地写法队列这块用什么都行核心是三件事任务入队时带上业务唯一标识、消费时先查是否已生成、失败时按退避策略重试。async function handleTask(task) { const key buildObjectKey(task.appid, task.scene, task.width); // 幂等检查已存在且校验通过就跳过 const exists await storage.headObject(key); if (exists exists.size 1024) { return { key, skipped: true }; } const buffer await generateSunCode(task.token, task); if (buffer.length 1024) { throw new Error(返回内容过小疑似错误响应); } await storage.putObject(key, buffer, { contentType: image/png }); return { key, skipped: false }; }那个内容过小的判断是个小技巧。正常的码图片至少几 KB如果拿到的内容只有几百字节八成是错误信息被当成了图片比如某些代理层返回的错误页。加个长度兜底能把一部分静默失败挡在前面。重试策略上我一般设置最多 3 次间隔按 1 秒、4 秒、16 秒递增。超过 3 次就标记为失败进死信队列人工介入。千万别无限重试遇到账号层面的权限问题重试一万次也是同样的错误只会把队列堵死。5.3 失败重试与可观测性批量任务最怕的是跑完了但不知道有多少张是坏的。所以从第一天起就要把统计埋进去总数、成功数、跳过数、失败数、失败原因分布。我在实际项目里会额外做一件事抽样验证。任务跑完后随机抽 1% 的码用图片库读一下尺寸和格式确认不是空文件也不是错误文本。这一步能捞出一批接口返回 200 但内容是错的的情况光看任务状态是发现不了的。日志里一定要记录 scene 和对应的错误码。因为失败往往是聚集性的——比如某一批 scene 里混进了非法字符或者某个 page 路径被下线了。有了 scene 和错误码的对应关系一眼就能看出是哪一类问题不用一条条翻。6. 复盘几个真实踩过的坑6.1 生成出来一片灰扫码没反应有次生成出来的码整体发灰扫码工具完全识别不了。查了半天原因是line_color传了品牌色里一个很浅的灰色和白色背景的对比度严重不足。码的识别依赖黑白对比颜色可以变但对比度必须够。稳妥的做法是要么用纯黑要么用深色亮度低于 30%别用中间调和浅色。还有个类似的情况是is_hyaline设成了 true然后设计师把透明底的码叠在了一张深色背景图上。透明区域的白其实是背景色深色背景下整体对比度反转识别率暴跌。透明底一定要配浅色背景或者干脆不用透明底。6.2 scene 里的中文与特殊字符前面提过 32 字符的限制但真正坑人的是编码。中文字符在 URL 编码后会变成%XX%XX%XX的形式一个汉字占 9 个字符。也就是说scene 里放 3 个汉字就吃掉 27 个字符额度剩 5 个字符啥也干不了。我的做法是彻底不传中文全部换成短码服务端映射。这样既解决了容量问题又顺手解决了特殊字符可能引发的解析异常。如果你确实必须传中文比如某些线下门店要求码里带门店名方便人工核对那就单独留一个短字段别和业务参数混在一起。6.3 开发版、体验版、正式版的 page 差异这个坑我踩过不止一次。开发者在本地新增了一个页面直接在开发版里生成码测试一切正常。然后提交代码、发布正式版用户扫同款参数生成的码却打不开。原因有两个层面。第一page路径在正式版里可能不存在——代码没发布上去或者路径大小写写错了而开发工具对大小写的容忍度比线上高。第二check_path如果关掉了生成动作不会报错你就一直以为没问题。我的习惯是所有测试都用正式发布后的页面路径跑一遍或者至少用体验版验证。开发版验证只能证明我的代码逻辑对不能证明用户能打开。6.4 图片存储后的缓存污染最后说一个特别隐蔽的问题。有次更新了一批码重新生成并覆盖了对象存储上的同名文件结果用户扫到的还是旧码。查下来是 CDN 缓存没刷新而 CDN 的缓存周期设的是 7 天。解决方案有两个思路。一是改 key 不改内容每次生成用新的哈希或带版本号的 key让 URL 天然变化CDN 自然回源。二是内容变了就主动刷新调用 CDN 的刷新接口清理对应 URL。前者更省心后者更省存储。我倾向第一种因为码这类资源一旦生成就基本不变重新生成通常意味着场景变了那就应该是一个新的 key。用旧的 key 覆盖从语义上讲本身就是错的。还有个细节私有桶 签名 URL CDN 的组合下签名过期会导致 CDN 回源失败此时如果 CDN 上有旧缓存还能撑一阵一旦缓存也过期用户就直接看到 404。这种延迟爆炸的问题最难排查所以我在开头就说能不用私有桶就别用。我个人在这些项目里最大的体会是码生成这活儿代码量不大坑全在边界条件上。参数长度、字符编码、二进制流、缓存、限频每一个单独拎出来都不难但它们在一条链路上串起来任何一个环节的处理不到位最后暴露出来的现象都是一样的——扫不出来或者打不开。所以排查的时候别从现象猜按链路一段段验证接口返回的是不是图片、图片能不能正常打开、尺寸够不够印、URL 能不能访问、访问到的是不是最新版本。这五步走完九成的问题都能定位。剩下的那一成多半是页面路径本身的问题去小程序后台看看版本状态就清楚了。