小程序故障排查：从日志到真机定位

小程序上线后出现故障，最难的往往不是修复，而是定位。线上没有控制台，用户描述模糊，开发者只能靠有限的日志和复现路径去推断。下面这套排查流程，是我处理过多起线上问题后沉淀下来的方法，按顺序执行能覆盖大部分场景。

第一步：先分清是环境问题还是代码问题

接到故障反馈时，先问三个问题：

• 是所有用户都异常，还是个别机型、个别版本？
• 是首次进入就失败，还是操作到某一步才失败？
• 最近是否发布过新版本、调整过云函数或后端接口？

如果只有部分用户异常，优先怀疑环境差异：微信版本、系统版本、网络状态、缓存数据。如果所有用户同时异常，且时间点与发布或后端变更吻合，基本可以锁定为代码或配置问题。

第二步：用小程序后台的错误日志缩小范围

微信小程序管理后台的「运维中心」提供了实时日志和错误查询能力。重点关注两类信息：

• JS 错误：堆栈信息能直接指出出错文件和行号，注意区分是业务代码还是第三方 SDK。
• 接口错误：关注 fail 回调的 errMsg，常见的有 request:fail timeout、request:fail ssl hand shake error、request:fail -2:net::ERR_FAILED，分别对应超时、证书问题和域名配置问题。

如果后台日志不足，可以在关键路径主动上报。用 wx.reportMonitor 或自建上报接口，把用户 openid、页面路径、关键参数、错误码一起带上，比只看堆栈有用得多。

function reportError(scene, err) {
  wx.request({
    url: 'https://api.example.com/log',
    method: 'POST',
    data: {
      scene,
      message: err && err.message,
      stack: err && err.stack,
      page: getCurrentPages().pop().route,
      system: wx.getSystemInfoSync().system,
      time: Date.now()
    }
  })
}

第三步：区分渲染层与逻辑层

小程序是双线程架构，渲染层（WebView）和逻辑层（JSCore）通过消息通信。很多「页面白屏」「数据不更新」的问题，根源在于两层不同步：

• 数据改了但视图没变：检查是否直接修改了 this.data 的属性而没有调用 setData，或者 setData 的路径写错。
• 视图卡顿但逻辑正常：多半是 setData 数据量过大，或在高频事件（滚动、输入）中频繁调用。可以拆分数据、合并调用、使用 wx.nextTick 延后处理。
• 页面白屏：先看是否 JS 报错中断了页面初始化，再看分包是否加载失败，最后检查基础库版本是否过低导致 API 不存在。

第四步：真机调试复现

开发者工具的表现和真机经常不一致，尤其是涉及原生组件、文件系统、网络请求的场景。复现时建议：

1. 用真机调试模式连接，打开 vConsole 查看运行时日志。
2. 在「开发版」中开启调试，避免正式版无法查看日志。
3. 对网络问题，用抓包工具确认请求是否发出、响应内容是否正确，排除是客户端解析问题还是服务端返回问题。
4. 清理缓存后重试，验证是否为本地缓存脏数据导致。

第五步：建立可复用的排查清单

把每次故障的结论整理成清单，下次遇到类似现象可以直接对照：

• 接口域名是否在合法域名列表中，是否使用了 https。
• 云开发环境 ID 是否与当前小程序匹配。
• 分包路径与 subPackages 配置是否一致。
• 权限相关 API 是否在用户拒绝后做了兜底。
• 生命周期顺序是否被打乱，比如 onLoad 中依赖的数据尚未就绪。

排查的本质是缩小假设范围，而不是凭经验猜。每排除一个变量，问题就离你更近一步。

故障排查能力最终会沉淀为工程质量：日志埋点是否充分、错误边界是否完整、发布流程是否可回滚。把这些基础工作做在前面，线上问题的平均定位时间会明显下降。