小程序白屏与卡顿排查实录

上周三晚上十一点，一个做本地生活的客户在群里丢来一句话：「用户说打开小程序一片白，你赶紧看看。」我打开后台，数据面板一切正常，接口成功率 99.6%。这种时候最怕的就是「你那边没问题」——因为用户那边是真的有问题。这篇就聊聊这两年我在小程序故障排查上踩出来的几条路，都是实战里磨出来的，不是教科书。

先分清是「谁的白屏」

白屏在小程序里至少有三种来源，处理方式完全不同：

• 启动阶段白屏：代码包还没下载完，或者 app.js 里 onLaunch 卡住了。
• 页面渲染白屏：页面栈进去了，但数据没回来，wxml 里全是空值。
• 组件级白屏：某个自定义组件报错，把整块区域吞了。

我的习惯是先让用户发一张截图，看顶部导航栏有没有出来。导航栏在、内容空，基本就是第二种；连导航栏都没有，那就是启动阶段的事。这一步能省掉一半瞎猜。

真机日志才是真相

开发者工具里跑得好好的，真机出问题，这种案例太多了。原因通常是基础库版本差异、机型兼容、或者网络环境。我一般会先让测试同学打开「调试模式」，再配合 vConsole 看报错。

如果用户不方便配合，那就靠自己的日志上报。我们项目里有个简单的封装，关键节点都埋点：

// utils/logger.js
const report = (tag, data) => {
  wx.reportEvent('mini_log', {
    tag,
    msg: JSON.stringify(data).slice(0, 500),
    ts: Date.now()
  });
};

// 在 onLaunch 里
App({
  onLaunch() {
    report('launch_start', { lib: wx.getSystemInfoSync().SDKVersion });
    // 初始化逻辑
    report('launch_end', {});
  }
});

别小看这两行，之前有个白屏就是 launch_start 有、launch_end 没有，说明 onLaunch 里某个同步请求挂了，一查是旧版本基础库不支持某个 API。

接口排查别只看状态码

很多人看到 200 就放心了，但小程序里「请求成功、数据为空、渲染白屏」是高频组合。我排查时固定看三样东西：

1. 响应体结构是否和前端解析逻辑一致（后端改字段没通知，老问题）。
2. 是否有跨域或域名未配置导致的静默失败（开发环境正常、线上失败）。
3. 请求是否真的发出去了——用 Network 面板看，有时候是 wxml 里条件渲染写错，压根没触发请求。

有个坑我印象很深：页面用了 wx:if 控制列表，初始值为 false，接口回来后忘了置 true，用户看到的就是一块空白。这种 bug 在开发者工具里因为热更新会「碰巧」正常，真机必现。

卡顿和内存问题怎么定位

卡顿比白屏难查，因为它不报错。我的做法是先排除渲染层：

• 用「性能面板」看 setData 的频率和体积，单次超过 256KB 就要警惕。
• 长列表一定用 scroll-view 或分页，别一次性 setData 几千条。
• 图片资源走 CDN，别把大图打进包里，包体积超过 2MB 首屏就明显慢。

如果 setData 都正常还是卡，那大概率是频繁的动画或定时器。有次一个倒计时组件 setInterval 没在 onHide 里清掉，页面切走后还在跑，用户反馈「用一会儿手机发烫」，查了半天才发现是它。

上线后才暴露的坑

最后说两个只在线上出现的情况。一是分包加载失败，用户网络差的时候，主包进来了但分包没下来，页面直接白。解决办法是给分包加载加个 fail 回调，提示用户重试，别让页面干等。二是版本更新后用户还在跑旧代码，微信有版本管理机制，但用户不重启小程序就不会更新，遇到「别人都好了就他不行」，先让他删掉小程序重新进。

故障排查这件事，说到底不是比谁技术强，是比谁信息全。日志埋得够细，问题就少猜一半。我现在接手新项目，第一件事不是看业务代码，是先确认日志和监控有没有到位——这比事后救火便宜太多了。