支付宝小程序二维码扫码后提示启动参数缺失

2026-10-24支付阿杰

结论

二维码中的“页面路径”和“启动参数”需要分开填写：

页面路径填写小程序路由：pages/courtDetail/courtDetail
启动参数填写查询字符串：business_id=18056&category_id=1&name=%E8%AF%84%E8%AE%BA%E7%BE%BD%E6%AF%9B%E7%90%83%E9%A6%86

扫码进入小程序时，应从 App.onLaunch(options) 或 App.onShow(options) 的 options.query 中读取启动参数。不要只在目标页面的 Page.onLoad(query) 中取值，否则可能出现开发者工具中运行正常，真机扫码时却提示参数缺失的问题。

中文参数值还需要经过 URL 编码，以免二维码生成或扫码解析时产生歧义。

正确配置方式

二维码生成页面可以这样配置：

页面路径：
pages/courtDetail/courtDetail

启动参数：
business_id=18056&category_id=1&name=%E8%AF%84%E8%AE%BA%E7%BE%BD%E6%AF%9B%E7%90%83%E9%A6%86

其中：

评论羽毛球馆

使用 encodeURIComponent 编码后的结果是：

%E8%AF%84%E8%AE%BA%E7%BE%BD%E6%AF%9B%E7%90%83%E9%A6%86

除非二维码生成入口明确要求填写“完整页面地址”，否则不要把页面路径写成：

pages/courtDetail/courtDetail?business_id=18056&category_id=1&name=评论羽毛球馆

生成页面既然分别提供了“页面路径”和“启动参数”两个字段，就应将路由和参数分开填写。

获取启动参数

可以在 app.js 中统一保存二维码传入的参数：

App({
  globalData: {
    launchQuery: {}
  },

  onLaunch(options) {
    this.saveLaunchQuery(options);
  },

  onShow(options) {
    // 小程序已经存在于后台时，再次扫码可能只触发 onShow
    this.saveLaunchQuery(options);
  },

  saveLaunchQuery(options) {
    const query = options && options.query ? options.query : {};

    if (Object.keys(query).length > 0) {
      this.globalData.launchQuery = query;
    }
  }
});

目标页面可以同时兼容页面参数和应用启动参数：

const app = getApp();

Page({
  onLoad(query) {
    const launchQuery = app.globalData.launchQuery || {};

    const businessId =
      query.business_id || launchQuery.business_id;

    const categoryId =
      query.category_id || launchQuery.category_id;

    const encodedName =
      query.name || launchQuery.name || '';

    let name = encodedName;

    try {
      name = decodeURIComponent(encodedName);
    } catch (error) {
      // 部分运行环境可能已经完成解码，此时直接使用原值
    }

    if (!businessId || !categoryId) {
      my.alert({
        title: '提示',
        content: '启动参数缺失'
      });
      return;
    }

    this.setData({
      businessId,
      categoryId,
      name
    });
  }
});

有些二维码生成入口或运行环境会自动解码参数，因此不要无条件重复调用 decodeURIComponent。

为什么开发者工具正常

开发者工具中的启动配置，往往会将参数直接模拟成当前页面的 onLoad(query) 参数。通过真实二维码扫码时，小程序会启动或被重新唤起，参数通常先传入应用生命周期的 options.query。

如果业务代码只读取页面参数：

Page({
  onLoad(query) {
    const businessId = query.business_id;
  }
});

扫码时就可能拿不到相应的值。

还需要检查的事项

如果按上述方式处理后仍然缺少参数，请继续确认：

pages/courtDetail/courtDetail 已在 app.json 的 pages 中声明。
二维码关联的是当前小程序，不是测试应用或其他应用。
线上发布的版本已经包含该页面和新的参数读取逻辑。开发者工具运行的是本地代码，而扫码进入的通常是线上版本。
启动参数使用半角字符 = 和 &，不要混入中文标点或空格。
生成二维码时，不要重复编码整个查询字符串。通常只需编码参数值，并保留 = 和 & 作为参数分隔符。
使用同一个二维码分别测试冷启动和后台唤起。代码需要同时处理 onLaunch 和 onShow。