
小程序码生成的起点不是写代码,而是先选对接口。微信开放文档提供三个生成接口:createQRCode 生成方形普通二维码,getwxacode 生成数量有限的小程序码,getwxacodeunlimit 生成数量不受限、可携带 scene 参数的小程序码。三者都必须由服务端调用,前端不能直接请求;凡是需要「一码一参数」或批量生成的场景,应选择 getwxacodeunlimit,把业务参数放进 scene 字段,而不是拼进 page 路径。本文按「接口选型 → 调用主体 → 参数逐项 → scene 编码 → page 约束 → 扫描取值 → 数量与频率 → 错误码反查」的顺序说明,所有字段、阈值与错误码均以微信开放文档当前口径为准,可逐项对照核验。
一、三种生成接口先选对
三个接口在外形、参数能力、数量上限上各不相同,选错接口通常会导致两类问题:一是参数传不进去,二是生成数量触顶后报「码个数超限」。下表按调用前需要确认的维度横向对照。
| 维度 | createQRCode | getwxacode | getwxacodeunlimit |
|---|---|---|---|
| 码的外形 | 方形普通二维码 | 圆形小程序码 | 圆形小程序码 |
| 参数能力 | 仅指定 path,无独立 scene | 支持 scene 字段 | 支持 scene 字段 |
| 数量上限 | 与 getwxacode 合计 100000 | 与 createQRCode 合计 100000 | 暂无数量限制 |
| 页面指定方式 | path 最大 128 字符,可带 query | page,不能带参数 | page,不能带参数 |
| 典型场景 | 页面固定、数量少的一次性物料 | 码数量少、页面固定的展示位 | 带货、溯源、一物一码、批量生成 |
选型判断可以简化为三条:需要带业务参数或数量可能超过十万,选 getwxacodeunlimit;只需跳转到固定页面、数量很少,选 getwxacode;只接受方形二维码样式且数量有限,选 createQRCode。官方文档明确指出,前两个接口的生成数量合计受 100000 限制,达到上限会返回错误码 45029,因此批量场景不应从这两个接口起步。

二、调用主体与前置条件
三个接口都属于服务端接口,不能在小程序前端、网页或 App 中直接调用,原因之一是调用需要携带接口调用凭证 access_token,而凭证由 AppSecret 换取,不应暴露在客户端。官方文档给出三种调用方式,各自适用不同的部署形态。
| 调用方式 | 凭证 | 适用场景 | 要点 |
|---|---|---|---|
| HTTPS 调用 | access_token | 自建服务端、传统后端 | POST 参数需转成 JSON 字符串,不支持 form 表单提交 |
| 云调用 | 云开发环境内免鉴权 | 使用微信云开发的项目 | 方法名 wxacode.getUnlimited 等,出入参和 HTTPS 调用相同 |
| 第三方平台代调用 | authorizer_access_token | 服务商代商家调用 | 接口所属权限集 id 为 17,需商家授权对应权限集 |
还有一项容易遗漏的前置条件:个人主体小程序必须先通过主体认证,才能生成并使用小程序码,否则相关接口会返回认证类错误码。调用前应确认账号主体类型与认证状态,避免在代码侧反复排查参数而问题实际出在账号侧。成功调用时接口直接返回图片二进制内容,请求失败时才返回 JSON 格式的错误信息,因此服务端需要按响应内容类型区分处理,不能一律按 JSON 解析。
三、getUnlimited 参数逐项说明
确认接口与调用方式后,按接口定义逐项核对入参。下表字段与默认值取自「获取不限制的小程序码」接口文档,可作为代码评审的对照表。
| 参数 | 必填 | 含义与约束 | 默认值 |
|---|---|---|---|
| access_token | 是 | 接口调用凭证,放在 URL 查询参数中 | 无 |
| scene | 是 | 最大 32 个可见字符,仅支持数字、大小写英文及部分特殊字符 | 无 |
| page | 否 | 扫描进入的页面,根路径前不加 /,不能携带参数 | 主页 |
| check_path | 否 | 是否检查 page 是否存在于已发布版本 | true |
| env_version | 否 | 要打开的小程序版本:release、trial、develop | release |
| width | 否 | 二维码宽度,单位 px,范围 280 至 1280 | 430 |
| auto_color | 否 | 是否自动配置线条颜色 | false |
| line_color | 否 | 线条颜色 RGB 对象,默认黑色 | r0 g0 b0 |
| is_hyaline | 否 | 是否需要透明底色 | false |
width 的取值只影响生成图片的像素尺寸,不影响扫描识别距离的全部因素,印刷物料还需结合材质与最小尺寸单独评估。auto_color 若设置后线条仍为黑色,说明接口判断当前主色调不建议改色,属于正常返回而非参数失效。
四、scene 传参规则与编码
scene 是「一码一参数」的核心字段,也是报错最集中的位置。官方文档规定 scene 最大 32 个可见字符,只支持数字、大小写英文以及部分特殊字符,完整合法集合为英文标点 ! # $ & ‘ ( ) * + , / : ; = ? @ – . _ ~。其它字符需要自行编码为合法字符。
| 参数形态 | 是否可直接传入 | 处理方式 |
|---|---|---|
| 数字与大小写英文 | 可以 | 直接使用,例如商品编号、用户标识 |
| 合法英文标点 | 可以 | 可作为分隔符,例如用短横线连接多个字段 |
| 中文 | 不可以 | 不能用 urlencode 处理,需改用其它编码方式或映射为英文 ID |
| 百分号 % | 不支持 | 接口明确不支持该字符,需自行替换为合法字符 |
| emoji 与空格 | 不可以 | 编码为合法字符后再传入 |
之所以强调中文不能用 urlencode,是因为编码结果会包含百分号,而百分号不在接口支持的字符集合内。工程上更稳妥的做法是让 scene 只承载一个短 ID,业务参数由该 ID 在服务端查询得到,既避开字符集限制,也避免把敏感信息写进可被解码的码图。
五、page 与 check_path 的约束关系
page 指定扫描后进入的页面路径,有两个硬性写法要求:根路径前不要加斜杠,例如写成 pages/detail/detail;不能携带参数,需要传的参数一律放进 scene。此外 scancode_time 是系统保留参数,不允许配置在 page 或 scene 中。
| check_path 取值 | 检查行为 | 对 page 的要求 | 数量约束 |
|---|---|---|---|
| true(默认) | 检查 page 是否存在于已发布小程序 | 必须是已发布版本存在的页面,否则报错 | 无额外页面数量约束 |
| false | 跳过页面存在性检查 | 允许小程序未发布或 page 不存在 | page 有数量上限 60000,请勿滥用 |
两者的取舍是:正式环境中保持默认 true,可以由接口提前拦截拼错的页面路径;只有在需要提前为尚未发布的页面批量备码时,才把 check_path 设为 false,并自行维护 page 台账,避免触及 60000 的页面数量上限。env_version 决定扫描打开的版本,调试阶段设为 develop 或 trial,正式投放前应确认回到 release。
六、扫描进入后如何取得 scene
生成端把参数写进 scene,消费端还要正确取出来,链路才算闭环。官方文档说明:scene 字段的值会作为 query 参数传递给小程序,用户扫描该码进入后,开发者可在页面参数中取得 scene 再做业务逻辑。

| 取值位置 | 适用时机 | 关键写法 |
|---|---|---|
| Page 的 onLoad(query) | 页面首次加载 | 对 query.scene 做 decodeURIComponent 后再使用 |
| wx.getLaunchOptionsSync() | 小程序首次启动 | 从返回对象的 query 中读取 scene 并解码 |
| wx.onShow 回调 | 小程序从后台回到前台 | 在回调参数 query 中读取并解码 |
| 开发者工具条件编译 | 调试模拟 | 自定义参数需先 encodeURIComponent 再模拟 |
需要区分两个容易混淆的字段:场景值 scene 与自定义参数 query.scene 并非同一概念,用户从小程序码进入时,业务参数位于 query.scene 中;文档示例反复强调该值需要经过解码才能得到生成时传入的内容。真机与开发者工具的差异也要留意:工具内自定义参数要求先编码再模拟,而真机扫描得到的是已编码后的值,直接按同一套解码逻辑处理即可。
七、数量上限与调用频率
数量与频率是批量生成场景必须提前核算的两项约束,超出后接口会返回明确的错误码。
| 约束项 | 适用接口 | 官方口径 | 应对方式 |
|---|---|---|---|
| 生成数量合计上限 | createQRCode 与 getwxacode | 合计 100000 个 | 批量场景改用 getwxacodeunlimit |
| 生成数量 | getwxacodeunlimit | 永久有效,数量暂无限制 | 仍建议按业务需要预生成并缓存 |
| 调用频率 | getwxacodeunlimit | 分钟频率受限,约 5000 次每分钟 | 大批量改为离线预生成,避免实时高峰 |
| check_path=false 的 page 数 | getwxacodeunlimit | 60000 个上限 | 维护 page 台账,不要构造随机路径 |
虽然不限量接口没有总数量上限,但调用频率仍受限,且生成图片属于计算与带宽开销较大的操作。上线前通常把码图预生成后存入对象存储,业务侧只保存图片地址与 scene 的对应关系,避免每次请求都实时调用生成接口。
请求体的写法也有一个高频错误点:官方文档明确三个接口都要求把 POST 参数转成 JSON 字符串提交,不支持 form 表单形式。若用表单方式发送,服务端可能返回参数长度或数据格式类错误(例如 40159),此时错误提示指向 path,实际根因是提交格式不对。成功响应是图片二进制流,失败响应才是 JSON,因此服务端应先用响应状态码与 Content-Type 分流,再决定按图片保存还是按错误码解析,避免把一张成功生成的图片当成 JSON 解析而报出看似无关的异常。
八、码图台账与存储约定
批量生成后,图片本身与 scene 的对应关系需要落库保存,否则后续无法核对来源,也难以在参数规则调整后重新生成。下表列出台账中建议保留的字段及其作用。
| 字段 | 记录内容 | 用途 |
|---|---|---|
| scene 原文 | 生成时传入的参数字符串 | 与业务对象一一对应,便于回溯 |
| 业务对象标识 | 商品、门店、设备等内部编号 | 把码图挂接回业务系统 |
| page 路径 | 扫描后进入的页面 | 页面调整时可筛选需重生成的码 |
| env_version | 生成时指定的小程序版本 | 区分调试码与正式码 |
| 图片存储地址 | 对象存储中的文件链接 | 业务侧直接取用,避免重复调用接口 |
| 生成状态 | 成功、失败、废弃等状态 | 失败项可按错误码批量重试 |
图片生成接口返回的是二进制内容,服务端需自行写入对象存储并保存地址。命名上建议以 scene 的哈希值作为文件名,使同一参数重复生成时可覆盖而非堆积副本;同时保留原始 scene 明文,避免只有哈希无法反查业务对象。
九、错误码反查
接口失败时返回 JSON,包含 errcode 与 errmsg。按下列顺序排查,可覆盖绝大多数生成失败场景。

| 错误码 | 含义 | 排查方向 |
|---|---|---|
| -1 | 系统繁忙 | 稍后重试,避免瞬时并发过高 |
| 40001 | 凭证无效或已过期 | 检查 AppSecret 是否正确、access_token 是否需要刷新 |
| 40097 | 参数错误 | 核对请求体是否为合法 JSON、字段拼写是否正确 |
| 40129 | scene 不合法 | 检查是否超过 32 个可见字符或含非法字符 |
| 40159 | path 长度非法 | path 不能为空且不超过 128 字符,请求需为 JSON |
| 40169 | scene 长度非法 | 缩短 scene 或改为短 ID 映射 |
| 41030 | page 路径非法 | 去掉根路径斜杠、移除参数、确认页面已发布,或设 check_path=false |
| 45029 | 码数量到达上限 | createQRCode 与 getwxacode 合计触顶,改用不限量接口 |
| 85096 | 含保留字段 scancode_time | 从 path 或 scene 中移除该字段 |
| 85412 / 85413 | 个人主体未认证 | 完成主体认证后再生成和使用小程序码 |
排查时不要只看 errmsg 的字面描述,应回到请求体逐字段核对,尤其是 scene 与 page。前者受字符集与长度双重约束,后者受写法与页面发布状态约束,两者叠加时错误信息可能只提示其中一项。
十、上线前自检清单
- 已根据是否需要动态参数与数量规模确认所用接口,批量场景使用 getwxacodeunlimit
- 调用发生在服务端,access_token 未出现在前端代码或公开配置中
- scene 不超过 32 个可见字符,且不含中文、百分号、emoji 等非法字符
- page 根路径前无斜杠、不带查询参数,scancode_time 未出现在任何字段
- check_path 按环境取值,正式环境为 true,关闭时已登记 page 台账
- env_version 在投放前确认回到 release,未停留在 develop 或 trial
- 消费端对 query.scene 做了解码,并区分场景值与自定义参数
- 大批量场景已改为预生成并缓存图片,调用频率与数量上限已核算
十一、常见问题
小程序二维码怎么生成?
由服务端调用 createQRCode 接口生成方形二维码,传入已发布页面的 path 与可选的 width,成功时接口直接返回图片二进制内容。若需要携带业务参数或批量生成,应改用 getwxacodeunlimit。
小程序码怎么弄?
小程序码由服务端接口生成,前端只负责展示生成好的图片或把图片地址下发。开发者工具中也支持在条件编译里模拟带 scene 的扫描调试,但正式码图仍需由接口生成。
小程序码生成没有参数怎么办?
先确认使用的是支持 scene 的接口,createQRCode 只有 path 字段;再检查 scene 是否符合 32 个可见字符与合法字符集约束,含中文或百分号会被判为非法参数。
小程序码在哪里找?
已发布小程序的码图通常由业务方在后台或自有系统生成并保存,接口只负责返回图片内容,不会自动归档。生成后应把图片与 scene 的对应关系存入自有台账,便于后续核对与复用。
小程序码怎么解码?
码图本身不需要解码,需要解码的是扫描进入后拿到的 query.scene。按文档示例对该值执行解码后再按业务规则拆分字段,即可得到生成时写入的内容。
小程序码能生成多少个?
getwxacodeunlimit 生成的小程序码永久有效、数量暂无限制;createQRCode 与 getwxacode 两个接口合计上限为 100000 个,达到上限会返回错误码 45029。
小程序生成二维码接口怎么调用?
通过 HTTPS POST 调用,参数为 JSON 字符串,凭证 access_token 放在 URL 查询参数中;也可在云开发中使用对应云调用方法,出入参与 HTTPS 调用相同。不支持 form 表单提交。
小程序码生成失败报 41030 怎么处理?
该错误表示 page 路径非法。检查根路径前是否多加了斜杠、path 中是否携带了参数、页面是否在已发布版本中存在;若确需指向未发布页面,可将 check_path 设为 false 并自行维护页面台账。
以上链路的核验路径是:先在服务端用固定的测试 scene 生成一张码图,确认接口返回图片而非 JSON 错误;再用真机扫描,在页面 onLoad 中打印解码后的 scene,确认与生成时一致;最后把错误码表与自身日志中的 errcode 对照,逐项收敛参数写法与账号状态。三步分别对应生成端、消费端与异常端,任一环节出现异常都可以独立定位。
配图说明:本文部分配图使用人工智能生成合成技术制作。





