一、基础库 & 宿主 App 版本兼容

1. 低版本微信 / 基础库无法启动

现象：打开白屏、直接闪退、控制台报API不存在、页面卡死

原因：代码使用高版本基础库独有 API / 组件 / 语法，未做版本判断；ES6 + 语法未降级转译

典型接口：wx.getUserProfile、隐私授权、订阅消息、新版地图、原生弹窗等

解决：用 wx.canIUse() 做能力判断，配置小程序后台最低基础库版本

2. 不同基础库行为不一致

现象：同一功能，新版基础库正常，旧版样式 / 交互 / 回调异常（如弹窗位置、分享逻辑、支付结果回调）

原因：官方迭代组件、接口逻辑，新旧版本规则不统一

测试要点：覆盖主流基础库区间，重点回归授权、支付、弹窗

3. 宿主 App 跨平台兼容（微信 / 支付宝 / 抖音 / 百度小程序）

现象：一套代码多端运行后，登录、支付、分享、跳转失效；样式错乱

原因：各平台 API、域名白名单、登录体系、路由规则互不通用

常见坑：微信wx.xxx、支付宝my.xxx接口混用；域名未逐个配置白名单

4. 小程序版本缓存不生效

现象：客户端一直加载旧包，更新版本后功能 / 样式不变

原因：本地缓存策略、冷启动规则问题；未触发强制更新逻辑

表现：老微信版本无法拉取新版小程序包

二、iOS 设备兼容问题

1. 刘海屏 / 灵动岛 / 底部小黑条适配异常

现象：顶部导航、按钮被状态栏遮挡；底部内容被安全区遮挡，按钮点击不到

原因：未使用 safe-area-inset 安全区样式，未适配全面屏

高发机型：iPhone X 及以上全系、灵动岛机型

2. 软键盘引发页面错位

现象：输入框唤起键盘，页面整体上移；收起键盘后页面无法回弹、留白、内容遮挡

衍生问题：弹窗 + 输入框组合场景错乱、滚动定位失效

原因：iOS 页面渲染、视口计算逻辑特殊，固定定位元素受键盘影响大

3. 老旧 iOS 机型卡顿、闪退、内存溢出

现象：iPhone 6/6P/SE 打开长列表、多图页面滑动卡顿；频繁切页后闪退

原因：机型内存 / 性能低，大图、未优化列表、过多动画加剧负载

4. 暗黑模式适配异常

现象：切换系统深色 / 浅色模式后，文字、背景色对比度不足、文字看不清、样式重叠

原因：未开启darkmode配置，缺少两套主题样式

5. 图片 / 视频 / 媒体资源异常

现象：图片裂图、加载空白；视频无法播放、无声、黑屏

原因：HTTPS 证书不合法、视频编码格式不兼容、跨域限制、大图片未压缩

6. 手势、滚动穿透

现象：弹窗浮层弹出后，底层页面仍可滚动；滑动手势冲突

iOS 该问题出现概率远高于安卓

三、Android 设备兼容

1. 厂商定制系统样式错乱

现象：华为、小米、OPPO、vivo、三星等机型，原生导航栏、按钮、字体、弹窗样式各不相同

典型：标题栏高度不一致、字体大小被系统强制修改、圆角 / 阴影失效

原因：安卓各厂商深度定制系统，篡改默认组件样式

2. 低端安卓机闪退、ANR、启动慢

现象：3G 及以下内存机型冷启动耗时久；长列表、多图页面直接闪退

原因：资源未懒加载、列表未做虚拟列表、图片未压缩、内存未及时释放

3. 底部导航 / 系统导航栏遮挡

现象：页面底部内容被安卓虚拟导航键（三大金刚键）遮挡

原因：未判断设备是否存在虚拟栏，未做底部安全区适配

4. 点击区域失效、点击延迟

现象：按钮点击无响应、需要多次点击；点击有明显延迟

原因：元素尺寸过小（小于官方最小点击区域）、移动端 300ms 点击延迟、层级被遮挡

5. 权限弹窗异常

现象：定位、相机、存储权限弹窗弹出失败、点击无反应、授权状态判断错误

原因：安卓不同版本权限机制变更（Android 10 + 分区存储、权限分级）；厂商拦截系统弹窗

6. 加载、缓存异常

现象：切换网络后页面数据不刷新；离线缓存内容错乱；分包加载失败

高发：低端机、弱网环境下分包加载超时

四、样式 & 布局兼容

1. 不同分辨率屏幕适配

现象：小屏手机内容溢出、文字截断；大屏手机元素拉伸、布局松散

原因：使用固定 px 单位，未采用rpx响应式单位

2. 字体兼容问题

现象：部分机型字体放大 / 缩小、特殊符号 / 图标字体显示方框（乱码）

原因：使用系统非默认字体、特殊图标字体未做兼容

3. 圆角、阴影、渐变失效

现象：部分安卓低端机 CSS 圆角、阴影、渐变样式消失

原因：老旧 WebView 内核不支持高阶 CSS 属性

4. 横屏 / 竖屏切换布局错乱

现象：设备旋转屏幕后，页面布局变形、元素重叠

原因：未适配横竖屏切换逻辑

五、网络兼容问题

1. 弱网 / 高延迟场景异常

现象：2G/3G、高延迟、丢包环境下，接口请求超时、页面空白、加载动画常驻、重复提交

原因：无超时判断、无加载状态、未做防抖防重

2. 网络切换异常

现象：Wi‑Fi 切移动网络、断网重连后，数据加载失败、状态卡死

原因：未监听网络状态变化，无异常重试、错误提示

3. HTTPS / 域名限制

现象：部分网络环境下资源、接口加载失败

原因：域名未配置小程序白名单、证书过期 / 不被信任、内网 / 境外域名访问受限

六、功能 & 组件 & 交互兼容

1. 原生组件冲突

现象：map、video、camera 等原生组件层级过高，浮层弹窗被穿透遮挡

全平台通用高频问题

2. 表单组件兼容

现象：单选、复选、开关在部分机型样式错乱；输入框联想、自动填充异常

3. 下拉刷新 / 上拉加载失效

现象：部分机型无法触发下拉刷新；上拉加载无限循环、重复请求数据

4. 分享、转发功能异常

现象：不同微信版本 / 机型，分享卡片图片、标题、链接展示异常；转发后打开页面错误

七、第三方能力 & 专项功能

1. 支付兼容

现象：拉起支付失败、支付完成后回调页面错乱、重复扣款判断异常

区分：微信支付、商户支付、境外支付，不同地区 / 版本规则有差异

2. 定位、地图服务

现象：部分机型定位不准、定位超时、地图加载空白

原因：系统定位权限关闭、国内 / 境外地图域名 / 服务差异

3. 扫码、拍照、相册

现象：相机无法唤起、拍照模糊、选择相册图片上传失败、图片旋转角度错乱（安卓尤为常见）

4. 推送、订阅消息

现象：低版本微信、安卓定制机收不到服务通知、订阅消息弹窗无法弹出

八、分包 & 包体积兼容

现象：低端机、弱网下主包 / 分包加载超时、加载失败；包体过大导致无法安装、启动闪退

原因：总包体积超出限制、分包拆分不合理、资源未按需加载