小程序兼容性测试的完整清单

小程序兼容性测试不是上线前跑一遍真机就结束的环节。它贯穿开发、联调、灰度、上线后的整个周期。设备型号、系统版本、微信客户端版本、屏幕形态、网络环境、权限状态，任意一个变量变化都可能让同一份代码表现不同。下面这份清单按测试维度组织，可以直接对照检查。

一、先明确兼容性测试的边界

很多团队把兼容性测试等同于“多买几台手机点点看”，结果覆盖了大量低价值机型，却漏掉了真正会出问题的组合。建议先划定范围：

• 基线设备：团队内部常备的 5～8 台真机，覆盖 iOS 最新两代、Android 主流品牌各一台、一台低端机。
• 长尾设备：通过云真机平台补充，重点覆盖折叠屏、平板、小屏机型、Android 高版本定制系统。
• 版本矩阵：微信客户端至少覆盖当前版本与前一个大版本；基础库版本要关注项目 miniprogramRoot 中声明的最低基础库。

范围确定后，把“哪些能力在哪些版本可用”写进项目文档，比每次临时判断可靠得多。

二、渲染层兼容：样式与布局

小程序的渲染层在不同平台分别由 WebView 和原生渲染承担，样式差异是最常见的兼容问题来源。

• 使用 rpx 做尺寸单位时，注意大屏设备上的等比放大是否符合预期，必要时对平板单独设置最大宽度。
• 安全区域适配：iPhone 刘海屏、灵动岛、Android 挖孔屏需要 env(safe-area-inset-bottom) 处理底部固定按钮，避免被系统手势条遮挡。
• 字体：部分 Android 机型默认字体渲染偏粗或行高不同，避免用固定高度容器承载多行文本。
• 滚动容器：scroll-view 在低端 Android 上嵌套滚动容易出现卡顿或滚动穿透，测试时要专门验证弹层打开后的背景滚动。

/* 底部安全区通用写法 */
.fixed-bar {
  padding-bottom: constant(safe-area-inset-bottom);
  padding-bottom: env(safe-area-inset-bottom);
}

三、逻辑层兼容：API 与基础库

逻辑层的问题往往更隐蔽，因为开发机上一切正常，换到低版本基础库才报错。

• 调用新 API 前用 wx.canIUse 判断，或检查基础库版本号，给出降级方案。
• 订阅消息、支付、直播、地图等能力对类目和版本有额外限制，测试账号要覆盖未授权、拒绝授权、授权后撤销三种状态。
• 存储：wx.setStorageSync 在部分机型上有容量限制，写入大对象前做体积校验。
• 时间与浮点：不同 JS 引擎对日期解析、浮点精度的处理存在差异，避免依赖 new Date('2024-01-01 00:00:00') 这类非标准格式。

四、网络与生命周期

弱网和异常生命周期是兼容性测试的高频盲区。建议在测试机上开启网络限速，模拟 2G、弱 3G 环境，观察：

• 首屏骨架屏是否正常展示，超时后是否有重试入口。
• 请求并发过多时是否触发域名并发限制。
• 切后台再回前台、来电中断、锁屏解锁后，页面状态是否错乱。
• 小程序被系统回收后重新进入，onLaunch 与页面栈的恢复是否符合预期。

五、权限与系统能力

定位、相册、摄像头、蓝牙、剪贴板等能力在不同系统上的授权弹窗样式和拒绝后的行为不一致。测试时要覆盖：首次请求、拒绝、拒绝后再次请求、系统设置中关闭权限、权限被其他应用占用等场景，并确保每种情况下页面都有明确提示，而不是白屏或静默失败。

六、把测试变成可重复的流程

兼容性问题的成本在于“难复现”。建议做三件事：

1. 维护一份设备清单表，记录机型、系统、微信版本、基础库版本和已知问题。
2. 在 CI 或提测流程中加入云真机自动化冒烟，至少跑通登录、首页、下单主链路。
3. 上线后接入异常监控，把 wx.onError、wx.onUnhandledRejection 与页面路径、设备信息一起上报，用真实数据反哺下一轮测试范围。

兼容性测试的目标不是覆盖所有设备，而是让“已知的差异”都有明确结论：要么适配，要么降级，要么在文档里写清楚不支持。

把上面几个维度拆成检查项，每次发版前按清单过一遍，比依赖个人经验更稳定。设备在变，基础库在变，清单本身也应该随项目持续更新。