发生了什么

换电地图是 App 里让用户查看附近换电柜的页面。用户在地图上选中一个站点后,会看到一个「导航」按钮,点下去期望直接拉起手机里的地图应用,按站点坐标规划好路线,跟着走就能到柜子跟前。

正常流程是:页面把站点的名称和经纬度交给 App 的容器,由容器提供的导航能力去完成跳转。这层能力不只负责打开地图应用,还负责判断手机上装了哪个地图应用、当前系统版本能用哪种跳转方式、以及一个都打不开时怎么给用户提示。

这一期换电地图接的是刚上线不久的新容器,前后只用过两轮。接导航时,开发没有调用容器已经封装好的导航能力,而是自己按模板拼出一条地图应用的路径规划链接,再交给容器的底层跳转通道打开。这条链接由应用本体标识、路径规划路径、目的地名称与经纬度以及几个固定参数拼成,走的是跳转外部应用的老办法。

结果在部分 iOS 版本上,用户点击「导航」按钮后页面毫无反应:没有拉起地图应用,也没有任何提示,按钮像是坏了。在系统版本不同的其他机型上,同样的点击能正常跳转。11 月 18 日收到用户反馈,排查后确认问题出在这条跳转链接上:它在 iOS 16 上存在兼容问题,低版本系统同样识别不了。

修复方向是改回调用容器封装好的导航能力,让版本差异交给能力层处理,预计 11 月 27 日发布,实际发布与验证结果待确认。

本质

一句话:这条路本来有一层专门处理系统差异的封装,业务代码绕过它自己拼链接,等于把版本兼容的责任搬到了业务代码里。

  1. 容器提供的导航能力是一个统一入口。它内部要判断目标地图应用是否安装、当前系统接受哪种跳转形式、参数怎么带,以及失败之后是降级还是提示。这些判断集中在一处,业务页面不需要知道细节。
  2. 这次接导航时,页面按固定模板拼链接:应用标识、路径规划路径、目的地名称与经纬度、几个固定参数。拼接时没有考虑不同系统版本可能接受不了这种写法,也没有准备第二条路径。
  3. 这条被写死的链接在部分 iOS 版本上没有被识别,系统没有拉起地图应用,跳转根本没有发生。
  4. 页面只负责发出跳转,没有检查结果,也没有兜底提示,所以失败对用户表现为「点了没反应」,对开发表现为没有任何报错。

同一段跳转代码把系统版本差异当成不存在,而失败又是静默的,问题因此只在部分机型上出现,回归时很容易漏掉。

底层通道能被直接调用,所以这段代码在接入时看起来是通的:它只在接入验证时的那一种环境下被观察过。真正稳定的做法不是把链接改到适配某个系统版本,而是回到统一入口,让能力层去选。

错误代码

// 换电地图页:点击「导航」按钮(脱敏教学示例)
function onNavigateClick(station) {
  // 自己按模板拼外部地图应用的路径规划链接:
  // 应用标识 + 路径 + 目的地名称与经纬度 + 固定参数
  var navUrl = MAP_ROUTE_PREFIX
      + 'dname=' + encodeURIComponent(station.name)
      + '&dlat=' + station.lat
      + '&dlon=' + station.lng
      + '&dev=0&t=3';
  // 为什么错:绕过容器封装好的导航能力,把一条写死的链接直接交给
  // 底层跳转通道。能不能打开取决于目标应用是否安装、当前系统版本
  // 是否接受这种写法,而这两件事这里一件都没有判断
  container.bridge.call('openURL', { url: navUrl });
  // 跳转没有发生也不会有回调走到这里,页面不给任何反馈
}

修复代码示例

// 同一按钮,改为调用容器统一封装的导航能力(脱敏教学示例)
function onNavigateClick(station) {
  var target = {
    name: station.name,
    lat: station.lat,
    lng: station.lng
  };
  // 修复:只把目的地交给能力层。可用应用、当前系统支持的跳转方式、
  // 参数格式这些判断都回到封装里,不再由业务页面拼链接决定
  container.navigation.open(target, {
    onSuccess: function () {
      // 已成功拉起地图应用
    },
    onFail: function (err) {
      // 失败变成可处理的结果,而不是静默停在原页面
      toast('没有找到可用的地图应用,请手动搜索站点位置');
      report(err);
    }
  });
}

下次遇到这些场景要警惕

  • 接入新容器或新版本提供的能力:先确认这类跨端动作有没有官方封装入口。导航、拨号、分享、拉起支付都属于「跳出 App」的动作,没有封装入口就先评审,不要自己拼链接。
  • 页面上出现「点了没反应」的按钮:把它当缺陷处理,而不是体验问题。检查点击后是否同时有成功和失败回调,失败分支有没有提示或者降级。
  • 给跳转类功能做兼容性回归:至少覆盖产品声明支持的最低系统版本和当前最新版本,再额外测一次「手机没装目标应用」。每台设备上都观察是否拉起目标应用、失败时页面有没有提示。
  • 跨端调用只在一种设备或一个系统版本上验证过:换一台不同系统版本或不同机型的设备复测同一入口,并把「按钮有没有反应」写进断言,不要只看日志里有没有异常。