邯郸小程序调试实录：真机踩坑记

我是知码客，在邯郸做小程序和 APP 开发。这几年接的活里，写代码大概占一半时间，另一半全花在调试上。尤其是小程序，开发者工具里跑得好好的，一到真机就各种幺蛾子。这篇文章不讲虚的，就聊聊我在邯郸本地项目里踩过的调试坑，以及现在比较顺手的排查套路。

开发者工具不是万能的

微信开发者工具的模拟器很省事，但它毕竟是个模拟环境。网络、性能、权限、微信版本，这几样东西它都还原不了。我一般把调试分成三层：

• 模拟器：只看布局和基础逻辑，快速迭代
• 真机预览：扫码在手机上跑，验证接口和交互
• 真机调试：连电脑看 console 和 network，定位具体问题

很多新手卡在第一步，以为模拟器没问题就万事大吉。实际上线后用户反馈白屏、按钮点不动，回头一看全是真机才暴露的问题。

邯郸客户案例：定位权限那点事

去年给邯郸丛台区一家连锁餐饮做点餐小程序，功能不复杂：扫码点餐、会员积分、附近门店。测试阶段一切正常，客户拿去店里试，反馈说「附近门店」永远只显示一家。

排查过程挺典型。模拟器里定位是模拟的，永远返回预设坐标，所以看不出问题。真机调试一连上，发现 wx.getLocation 返回的精度很低，而且部分安卓机直接走了失败回调。原因有两个：一是没有在 app.json 里声明 requiredPrivateInfos，二是用户授权时选了「仅本次允许」，下次进来又得重新弹窗。

// app.json 里补上声明
{
  "requiredPrivateInfos": ["getLocation"],
  "permission": {
    "scope.userLocation": {
      "desc": "用于展示您附近的门店"
    }
  }
}

改完之后还得处理授权失败的分支，给个默认城市兜底。这类问题在本地生活类小程序里特别常见，邯郸做小程序的朋友大概率都会遇到。

真机调试的实用技巧

1. 打开 vConsole 看日志

线上环境看不到 console，可以引入 vConsole，在测试版里挂上去。真机调试模式下其实也能看，但 vConsole 更适合给客户或测试同事用，他们不用连电脑。

2. Network 面板要看请求耗时

小程序真机调试的 Network 面板能看每个请求的耗时和返回。我遇到过一次列表加载慢，模拟器里 200ms，真机上 3 秒。最后发现是图片没压缩，一张 banner 图 2MB，弱网下直接卡住。这种问题只能真机测。

3. 用 wx.getSystemInfoSync 排查兼容

const info = wx.getSystemInfoSync()
console.log(info.platform, info.system, info.SDKVersion)

把机型、系统版本、基础库版本打出来，很多「只有某款手机有问题」的 bug 一下就清晰了。我习惯在全局的 onLaunch 里打一次，出问题时让客户截图发过来。

云开发项目的调试差异

现在不少邯郸的小程序项目我会用云开发，省掉服务器运维。云开发的调试有个坑：云函数本地调试和云端环境不一致。本地跑通的云函数，部署上去可能因为环境变量、依赖版本报错。

我的做法是云函数里统一加日志，关键节点打 console.log，然后在云开发控制台的日志里看。另外云函数超时时间默认 3 秒还是 5 秒，涉及第三方接口调用时容易超时，记得在配置里调大。

上线前的自查清单

调试到最后一步是提审。我整理了一份自己的清单，每次上线前过一遍：

• 真机预览在 iOS 和安卓各测一遍
• 检查所有 wx.request 的域名是否已配置
• 隐私协议和用户授权弹窗是否合规
• 分包加载是否正常，主包体积是否超限
• 体验版给客户走一遍完整流程

说到底，小程序调试没有捷径，就是真机多测、日志多打、边界多想。在邯郸做小程序这几年，我发现客户最在意的不是功能多花哨，而是打开就能用、点了有反应。调试做扎实，上线后少挨骂，这比什么都实在。如果你也在邯郸做小程序开发，欢迎交流踩坑经验。