微信小程序码的开发，一上来就急着调接口，结果生成出来的码要么尺寸不对，要么场景值传参后死活拿不到数据。其实小程序码背后藏着不少细节，今天咱们就把整个流程掰开揉碎，从“为什么”到“怎么做”彻底讲清楚。

先纠正一个常见的误区：小程序码和小程序二维码是两回事。二维码是静态的，扫码后直接跳转指定页面；而小程序码是动态的，可以携带自定义参数，而且官方对小程序码的生成次数没有限制（二维码有数量上限）。更重要的是，小程序码支持B区（码眼区域）自定义颜色，甚至能嵌入logo，这在品牌传播里非常实用。

一、搞清楚你该用哪种接口

微信官方提供了三个生成小程序码的接口，选错就是因为没理解它们的区别。第一个是wxacode.get，它生成的码数量有限制，适合临时测试。第二个是wxacode.getUnlimited，这个接口不限量，而且能传递scene参数——注意，这里的scene参数是重点，后面会详细说。第三个是createQRCode，生成的是二维码而非小程序码，而且有数量限制。

实际开发中，99%的场景应该用getUnlimited。举个例子：你做一个活动页面，每个用户分享出去的小程序码都要带上自己的邀请码，这时候就必须用getUnlimited，因为它的scene参数可以动态变化。而get接口生成的码是固定的，只能跳转到固定页面。

二、拿到接口权限的隐藏门槛

调接口时报错"invalid scene"或者"access token invalid"，其实不是代码写错了，而是权限没开对。首先，你的小程序必须经过微信认证（就是那个每年交300块钱的认证），否则接口返回的数据是空的。其次，需要在微信公众平台后台的开发 -> 开发设置 -> 扫普通链接二维码打开小程序里，把你要跳转的页面路径配置进去。这一步漏掉，结果码生成了但扫不出来。

另外，scene参数的长度限制是32个字符，而且只能包含数字、大小写字母、下划线、连字符。如果你传了中文字符或者特殊符号，接口会直接报错。有个取巧的办法：把中文用encodeURIComponent转义后再传，但接收端要记得解码。

三、生成码的完整代码示例（附带坑点）

假设你的后端用Node.js，下面这段代码可以生成小程序码并返回给前端：

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

async function generateCode(scene, page) {
  // 1. 先拿access_token，注意这个token每天有2000次限制
  const tokenRes = await axios.get('https://api.weixin.qq.com/cgi-bin/token', {
    params: {
      grant_type: 'client_credential',
      appid: '你的appid',
      secret: '你的secret'
    }
  });
  const accessToken = tokenRes.data.access_token;

  // 2. 调用getUnlimited接口
  const response = await axios.post(
    `https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token=${accessToken}`,
    {
      scene: scene,  // 比如 'inviter=12345'
      page: page,    // 比如 'pages/activity/index'
      check_path: false, // 不校验页面是否存在，加快速度
      env_version: 'release' // 正式版
    },
    { responseType: 'arraybuffer' } // 关键！返回的是二进制图片数据
  );

  // 3. 保存成图片文件
  fs.writeFileSync('qrcode.png', response.data);
}

这里有几个容易翻车的地方：responseType必须设置成arraybuffer，否则拿到的是一堆乱码。另外check_path参数，如果你在开发阶段频繁修改页面路径，建议设为false，否则路径稍微不对接口就报错。但上线前一定要改回true，防止用户扫到不存在的页面。

四、场景值传递的“暗坑”

小程序码最核心的能力就是通过scene传递参数，但扫码后发现拿不到参数。问题出在页面生命周期上。假设你的码指向pages/activity/index，那么在这个页面的onLoad方法里，options对象就能拿到scene参数。但注意：冷启动和热启动的场景不同。

如果用户是第一次打开小程序（冷启动），scene参数在onLoad的options里。但如果用户已经打开过小程序，扫码后是热启动，这时候onLoad不会触发，参数会跑到onShow里。所以正确的做法是：

Page({
  onLoad(options) {
    // 冷启动时这里拿scene
    if (options.scene) {
      this.handleScene(options.scene);
    }
  },
  onShow(options) {
    // 热启动时这里拿scene
    if (options.scene) {
      this.handleScene(options.scene);
    }
  },
  handleScene(scene) {
    // 解码scene参数
    const params = decodeURIComponent(scene);
    console.log('获取到的参数：', params);
  }
});

还有一点：scene参数在onLoad里是字符串，但在onShow里可能是undefined，具体取决于微信版本。保险的做法是两个生命周期都处理，并且用decodeURIComponent解码——因为微信会对scene做一次编码。

五、小程序码的视觉定制（品牌必看）

默认的小程序码是黑白两色，但官方允许你改颜色。在请求参数里加上line_color字段，比如：

{
  "line_color": {"r": 255, "g": 128, "b": 0}
}

这样码眼和线条就变成橙色了。但注意：不要用太浅的颜色，否则扫码时识别率会下降。另外is_hyaline参数可以生成透明底的小程序码，适合放在设计复杂的海报上。

如果你想让码更好看，可以在码周围加一圈白边，但别加太宽，否则微信会判定为违规。有个小技巧：生成码后在图片外围留出至少10像素的空白区域，这样用户扫码时不会误触到旁边的元素。

六、性能优化：别每次都调接口

生成小程序码的接口虽然不限次数，但access_token每天只能获取2000次。如果你的并发量高，比如双十一活动，每个用户生成码都去拿一次token，很快就用完了。正确的做法是：把token缓存起来，有效期是7200秒，但建议提前半小时刷新，避免刚好过期时大量请求失败。

另外，同一个scene参数的小程序码可以重复使用。比如一个商品详情页的码，只要商品ID不变，生成的码就是一样的。建议在服务端把码存到CDN或对象存储里，下次请求时直接返回图片URL，而不是重新生成。这样既省token，又加快响应速度。

七、调试时的一个救命技巧

开发阶段扫码测试很麻烦，每次都要真机扫。其实可以用微信开发者工具的“通过二维码编译”功能，填入你生成的小程序码图片，工具会模拟扫码行为。但注意：这个功能只支持getUnlimited接口生成的码，get接口的码不行。

如果你发现扫码后页面空白，大概率是路径写错了。检查page参数是否以“/”开头——官方要求以“/”开头，比如“/pages/index/index”，但习惯写成“pages/index/index”，少了斜杠就会报错。另外，检查页面是否在app.json里注册过，没注册的页面跳转不了。

最后说一个不知道的细节：小程序码的有效期是永久，但如果你修改了码指向的页面路径，旧码仍然能用，只是会跳转到新页面。所以做活动时，哪怕活动结束了，也别急着删码，可以改成跳转到活动总结页，这样用户扫到旧码还有后续转化。