小程序开发

南京小程序码怎么生成?2026 三种接口选型、scene 传参、扫描取值与错误码反查清单

2026年11月18日

专业技术文章

南京小程序码怎么生成?2026 三种接口选型、scene 传参、扫描取值与错误码反查清单

发布时间:2026年11月18日
|作者:易企达网络|来源:南京易企达网络科技有限公司||
浏览:1,859
小程序码怎么生成封面
小程序码生成:三种接口选型、参数约束、扫描取值与错误反查

小程序码生成的起点不是写代码,而是先选对接口。微信开放文档提供三个生成接口: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 再做业务逻辑。

扫描小程序码取值链路信息图
扫描取值链路:读取 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 对照,逐项收敛参数写法与账号状态。三步分别对应生成端、消费端与异常端,任一环节出现异常都可以独立定位。

配图说明:本文部分配图使用人工智能生成合成技术制作。

《南京小程序码怎么生成?2026 三种…》是我们在南京做小程序开发时的实际实施记录。费用与交付范围以双方合同及平台当期规则为准。需要评估自己的项目,可以到联系页留下需求与预算范围。

相关文章

南京小程序图片上传与压缩怎么配置?2026 选图、压缩、上传链路与失败排查清单

南京小程序图片上传与压缩怎么配置?2026 选图、压缩、上传链路与失败排查清单

小程序图片上传是否稳定,取决于四段链路:选图参数是否用对、压缩是否在正确时机执行、上传地址是否在合法域名内、返回地址是否...

2026年11月21日

南京小程序 web-view 怎么配置?2026 业务域名、双向通信、跳转限制与白屏排查清单

南京小程序 web-view 怎么配置?2026 业务域名、双向通信、跳转限制与白屏排查清单

小程序 web-view 能否按预期工作,取决于四个前置条件:主体类型、业务域名与校验、通信是否遵守 postMessa...

2026年11月21日

南京小程序分享转发怎么配置?2026 转发灰色排查、带参归因与朋友圈限制清单

南京小程序分享转发怎么配置?2026 转发灰色排查、带参归因与朋友圈限制清单

小程序分享转发的可用前置条件是页面级回调、未隐藏菜单、认证备案与版本兼容。转发给朋友与分享到朋友圈是两套独立能力,字段、...

2026年11月20日

南京小程序数据埋点怎么设置?2026 留存口径、事件模型与上报失败排查清单

南京小程序数据埋点怎么设置?2026 留存口径、事件模型与上报失败排查清单

小程序数据埋点能否支撑留存分析,结论取决于指标口径、事件模型与上报链路是否先定死。基础统计做大盘校准,自定义分析做单事件...

2026年11月20日

南京小程序本地存储怎么配置?2026 容量上限、隔离规则、同步异步与清理策略清单

南京小程序本地存储怎么配置?2026 容量上限、隔离规则、同步异步与清理策略清单

小程序本地存储的结论先行:storage 独立于代码包,按用户维度隔离,单 key 上限 1MB、同一用户同一小程序总量...

2026年11月19日

南京小程序版本灰度与回滚怎么操作?2026 全量与分阶段发布、版本回退与异常反查清单

南京小程序版本灰度与回滚怎么操作?2026 全量与分阶段发布、版本回退与异常反查清单

小程序版本发布与回退的结论先行:全量发布即时覆盖用户,分阶段发布在十五天内按自定义比例逐步覆盖并默认到期全量;撤销分阶段...

2026年11月19日