微信小程序 UnlimitedQRCode 详解：page 与 scene 参数实战用法

在微信小程序开发中，UnlimitedQRCode（获取不限制小程序码） 是线下推广、渠道溯源、私域引流的核心能力。它最大的优势是生成数量无上限、永久有效，完美解决了普通小程序码有生成数量限制的痛点。

本文将带你全面认识 UnlimitedQRCode，重点拆解核心参数 page 和 scene 的用法，搭配实战代码，让你快速上手生成、使用无限小程序码！

一、UnlimitedQRCode 是什么？核心优势

UnlimitedQRCode 是微信官方提供的服务端接口（wxacode/getUnlimitedQRCode），用于生成永久有效、无数量限制的小程序码。

核心特点

1. 无生成上限：区别于有限制的普通小程序码，适合海量线下场景；
2. 永久有效：生成后不会过期，一码通用；
3. 自定义传参：通过 scene 传递业务参数，实现精准溯源 / 跳转；
4. 适用场景：渠道统计、商品溯源、门店码、用户分享、线下物料等。

二、关键前提：接口调用规则

1. 必须服务端调用小程序前端无法直接调用该接口（会暴露密钥），必须在你的后端服务（Node.js/Java/PHP 等）发起请求。
2. 接口地址plaintextPOST https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token=你的接口调用凭证
3. 依赖 access_token通过小程序 AppID + AppSecret 获取，是调用所有微信接口的凭证。

三、核心参数：page 和 scene 深度用法

这两个参数是 UnlimitedQRCode 的灵魂，直接决定扫码跳转页面和业务数据传递，也是开发者最容易踩坑的点。

1. page：扫码后跳转的页面路径

作用

指定用户扫码后，小程序打开的目标页面，不传默认跳转到首页。

格式要求

• 路径为小程序根目录开始的相对路径，不带任何后缀（.js/.wxml 都不用写）；
• 页面必须在 app.json 中注册；
• 仅支持开发版 / 体验版 / 正式版已存在的页面。

正确示例

plaintext

pages/index/index        // 首页
pages/goods/detail       // 商品详情页
pages/store/index        // 门店页面

错误示例

plaintext

/index/index       ❌ 缺少 pages 根目录
pages/goods/detail.html ❌ 带了后缀

2. scene：自定义业务参数（核心传参）

作用

UnlimitedQRCode 唯一的传参载体，用于传递自定义业务数据（如渠道 ID、商品 ID、用户 ID、门店编号等）。

严格限制（必看！）

1. 长度：最大 32 个字符（超长度直接报错）；
2. 字符集：仅支持 数字、大小写英文、!#$&*()=:/,;+-?_@；
3. 无格式限制：推荐用 key=value&key=value 自定义拼接规则。

实用示例

plaintext

channel=1001                // 渠道编号
goods=123&uid=456            // 商品ID+用户ID
store=789&activity=newyear   // 门店+活动标识

四、完整实战：从生成二维码到接收参数

我们分服务端生成二维码 + 小程序端接收参数两步，完整演示 page 和 scene 的使用。

步骤 1：服务端生成无限小程序码（Node.js 示例）

以最常用的 Node.js 为例，调用接口生成二维码图片（返回二进制流）：

javascript

运行

const axios = require('axios');
const fs = require('fs');

// 1. 获取 access_token（正式环境需缓存，2小时有效期）
async function getAccessToken() {
  const res = await axios.get('https://api.weixin.qq.com/cgi-bin/token', {
    params: {
      grant_type: 'client_credential',
      appid: '你的小程序AppID',
      secret: '你的小程序AppSecret'
    }
  });
  return res.data.access_token;
}

// 2. 生成 UnlimitedQRCode
async function createUnlimitedQRCode() {
  const accessToken = await getAccessToken();
  
  // 核心：配置 page 和 scene
  const params = {
    page: "pages/goods/detail", // 跳转商品详情页
    scene: "goods=10086&channel=offline", // 自定义参数：商品ID+渠道
    width: 430, // 二维码尺寸
    auto_color: false,
    is_hyaline: false // 是否透明底色
  };

  // 调用微信接口
  const res = await axios({
    method: 'POST',
    url: `https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token=${accessToken}`,
    data: params,
    responseType: 'arraybuffer' // 接收图片二进制流
  });

  // 保存二维码到本地（正式环境可返回给前端/上传云存储）
  fs.writeFileSync('./unlimited-qrcode.png', res.data);
  console.log("无限小程序码生成成功！");
}

createUnlimitedQRCode();

步骤 2：小程序端接收 scene 参数（核心）

用户扫码进入小程序后，在页面的 onLoad 生命周期中获取参数，scene 参数会被微信自动编码，需要解码后解析：

javascript

运行

// pages/goods/detail.js
Page({
  onLoad(options) {
    // 1. 获取扫码传递的 scene 参数（核心）
    const sceneStr = options.scene;
    if (!sceneStr) {
      console.log("非扫码进入");
      return;
    }

    // 2. 解码：微信会自动编码，必须用 decodeURIComponent 解析
    const decodeScene = decodeURIComponent(sceneStr);
    console.log("解码后的参数：", decodeScene); 
    // 输出：goods=10086&channel=offline

    // 3. 解析为对象，方便业务使用
    const sceneObj = this.parseScene(decodeScene);
    console.log("业务参数：", sceneObj);
    // 输出：{ goods: "10086", channel: "offline" }

    // 4. 业务逻辑：根据商品ID加载数据、根据渠道统计来源
    this.loadGoodsDetail(sceneObj.goods);
  },

  // 工具函数：解析 scene 字符串为对象
  parseScene(str) {
    const obj = {};
    str.split("&").forEach(item => {
      const [key, value] = item.split("=");
      obj[key] = value;
    });
    return obj;
  },

  // 加载商品详情
  loadGoodsDetail(goodsId) {
    console.log("加载商品：", goodsId);
  }
});

五、高频避坑指南（90% 开发者都踩过）

1. scene 长度超限超过 32 个字符直接生成失败，精简参数！
2. page 路径错误必须是 pages/xxx/xxx 格式，且页面已在 app.json 注册。
3. scene 用了非法字符不要用中文、空格、特殊符号（如 %^[]），严格遵守官方字符集。
4. 前端直接调用接口绝对禁止！会泄露 AppSecret，必须走服务端。
5. 没解码获取不到参数微信会编码 scene，一定要用 decodeURIComponent 解析。
6. 开发版调试生成的二维码必须用对应开发版 / 体验版扫码，正式版不兼容开发版页面。

六、总结

UnlimitedQRCode 是小程序线下运营的神器，而 page 和 scene 是它的核心：

• ✅ page：控制扫码跳转的页面，严格遵循路径格式；
• ✅ scene：承载自定义业务数据，控制长度 + 字符集，解码后使用；
• ✅ 全流程：服务端生成 → 小程序端解码使用 → 实现业务溯源 / 跳转。

掌握这两个参数，你就能轻松实现海量小程序码的生成与业务对接，适配所有线下推广场景！

关键点回顾

1. UnlimitedQRCode 无数量限制、永久有效，服务端调用；
2. page = 跳转页面路径（pages/xxx/xxx）；
3. scene = 自定义参数（≤32 字符，解码后使用）；
4. 小程序端通过 onLoad(options.scene) 获取参数。