微信公众号自定义菜单跳转小程序，onLoad中如何正确获取参数？

公众号自定义菜单支持直接跳转到已关联的小程序，配置时可以在页面路径后面附加查询字符串。这些参数会跟随小程序启动一起进入页面实例，onLoad 的第一个参数 options 就是它们的接收位置。理解这一过程的触发顺序和参数格式，能避免绝大多数参数丢失问题。

自定义菜单跳转小程序的参数传递路径

在微信公众号后台的菜单配置里，选择菜单类型为“跳转小程序”后，需要填写小程序的 AppID、页面路径以及备用网页。页面路径并不是普通的网址，而是小程序内部的页面地址，例如 pages/detail/detail。如果需要携带参数，可以直接在路径后面拼接查询字符串，格式为 pages/detail/detail?id=1001&from=menu。这里的 id 和 from 就是页面获取到的参数键名。

有一点必须注意：页面路径不能以斜杠开头，也不能包含协议头。路径中如果包含中文、空格或特殊符号，最好先进行 URL 编码，否则在菜单保存或用户点击后可能出现参数被截断的情况。例如商品名称作为参数传递时，建议使用 encodeURIComponent 处理后再拼接到路径末尾。

// 公众号后台菜单配置中的小程序页面路径示例
pages/detail/detail?id=1001&from=menu&title=iPhone%2015

从菜单点击进入小程序时，微信客户端会直接打开配置的页面路径，并把查询字符串解析后传给页面实例。整个链路是同步的，也就是说，页面开始加载时参数已经就绪，不需要额外请求接口获取。这比通过二维码进入的场景要简单，因为二维码通常会使用 scene 参数，而菜单跳转直接使用 query 参数。

在 onLoad 生命周期中接收参数的具体实现

小程序页面加载的第一步就是触发 onLoad 生命周期函数，它接收一个参数 options，里面存放着打开页面时携带的所有查询参数。如果菜单配置的路径是 pages/detail/detail?id=1001&from=menu，那么 options 对象中会包含 id 和 from 两个键，值分别为字符串 '1001' 和 'menu'。

Page({
  onLoad(options) {
    // options 的类型是对象，键值都为字符串
    console.log(options.id);   // '1001'
    console.log(options.from); // 'menu'

    // 如果需要数值类型，记得做转换
    const goodsId = Number(options.id);
    this.setData({
      goodsId,
      source: options.from || 'default'
    });
  }
});

上面的代码演示了最基本的参数获取方式。实际开发中，建议在 onLoad 里完成首屏渲染所需的数据初始化，因为 onLoad 只会触发一次，适合作为参数转换和请求入口。但要注意，options 中的值全部是字符串，即便你在路径中写了纯数字，也需要手动转换为 Number 或 BigInt 等类型。

如果参数值在菜单配置时经过了 URL 编码，例如 title=iPhone%2015，小程序端获取到的值会自动解码吗？答案是：菜单跳转场景下，微信客户端已经帮你解码好了，options 中拿到的是原始中文或空格。但为了避免个别基础库版本差异，可以自行做一次 decodeURIComponent，注意要包裹在 try-catch 中，防止非法编码导致异常。

Page({
  onLoad(options) {
    let title = options.title || '';
    try {
      title = decodeURIComponent(title);
    } catch (e) {
      console.warn('参数解码失败', e);
      title = '';
    }
    this.setData({ title });
  }
});

另外，onLoad 的 options 还可以通过小程序全局的 getLaunchOptionsSync 方法获取，但那只适用于冷启动时的参数。如果是热启动或者从其他页面返回，建议还是使用页面级 onLoad，因为它更贴近当前页面的上下文。

参数丢失的常见原因与调试技巧

很多情况下页面拿不到参数，并不是代码写错了，而是菜单配置阶段就出了问题。第一个高发原因是页面路径填写不完整，例如只写了 pages/detail/detail，却没有拼接 ?id=1001。第二个原因是路径里带了前导斜杠，比如 /pages/detail/detail?id=1001，这会导致微信无法正确识别小程序页面路径。第三个原因是参数值中包含未编码的 & 或 = 符号，解析时会被误认为新的键值对分隔符。

调试参数问题的最好办法是使用微信开发者工具的“普通编译”功能，在编译模式里手动填入启动页面路径和参数。例如设置启动页面为 pages/detail/detail，启动参数为 id=1001&from=menu，然后重新编译，就可以模拟菜单跳转的启动场景。这样做能快速确认是页面代码问题还是菜单配置问题。

// 在 app.js 中打印冷启动参数，辅助排查菜单跳转
App({
  onLaunch(options) {
    console.log('小程序启动参数：', options);
    console.log('query 参数：', options.query);
  }
});

如果开发者工具中能正常拿到参数，但真机上菜单跳转仍然获取不到，检查一下菜单是否关联了正确的小程序，以及小程序的开发版本和线上版本是否同步。有时菜单指向的是已发布版本，而真机调试使用的是开发版本，两者的页面路径可能不一致。此时可以临时把菜单改成跳转到备用网页，再把网页重定向到小程序，但更推荐直接在菜单里指向正确的正式页面路径。

最后要提醒的是，从公众号菜单跳转进入小程序时，options 中不会包含 scene 字段，除非你使用了短链接或其他带有场景值的通道。如果业务逻辑需要区分菜单来源，建议在菜单路径中显式添加 from=menu 这样的自定义参数，这样落地页可以准确记录用户渠道，后续做数据分析时也不会混淆。

微信公众号自定义菜单小程序参数获取onLoad生命周期修改时间：2026-09-23 20:13:31