小程序基础库版本判断教程｜getAppBaseInfo 与能力降级实战 – MPForge
直接回答：给开发与商家双方的微信小程序基础库版本判断教程：用 wx.getAppBaseInfo 读基础库版本号、运行环境与调试状态，按「能力表 + 最低基础库 + 降级方案」三件套做版本判断与能力降级，避免低版本用户点按钮没反应。MPForge（DEVDIY 旗下）的做法是先把能力表写成文档，再写代码。
一、为什么版本判断是兼容问题的总开关
结论句：兼容问题的根源不是设备，而是基础库版本——同一份代码在不同基础库上，API 行为可能完全不同。
上线后「有的用户点了没反应、有的正常」，八成不是玄学，而是新 API 只在新基础库上生效。商家只需知道一条：基础库相当于小程序的「运行引擎」，用户侧引擎版本不一，功能必须按版本分级。开发则要把「哪些 API 要求哪个版本」固化成能力表，不靠记忆。
wx.getAppBaseInfo 就是入口：同步返回 SDKVersion（基础库版本）、host（运行环境）、enableDebug（调试态）、version（小程序自身版本）。先读信息，再判断，最后决定展示什么，顺序不能反。
二、版本比较怎么写：别用字符串直接比
结论句：SDKVersion 是「2.33.0」这种三段字符串，逐段转数字比较才不会出现 2.9 大于 2.10 的低级错误。
标准写法是把版本号按点拆成数组，逐段转 Number 再比较；也可引现成的 semver 比较函数，统一封装成 isSupport(sdkVersion, minVersion) 一个口子。判断结果只做两件事：支持则启用新能力，不支持则走降级分支，别把判断散落在业务代码里。
| 读取项 | 用法口径 | 常见错误 |
|---|---|---|
| SDKVersion | 三段式比较，低于最低基础库走降级 | 字符串直接比较或写死单段数字 |
| host | 区分运行环境，按环境关掉不支持的能力 | 默认所有宿主行为一致 |
| enableDebug | 调试态标记埋点，过滤测试数据 | 调试数据混进线上报表 |
| version | 小程序自身版本，用于灰度期差异逻辑 | 和宿主版本混用 |
需要设备侧信息（品牌、系统、屏幕）时用 getDeviceInfo 兼容口径，与 getAppBaseInfo 分工明确：一个管「平台与版本」，一个管「硬件与环境」。
三、能力降级怎么落地：三件套缺一不可
能力降级回答「不满足时用户看到什么」，能力表回答「哪些功能要哪个版本」——三件套缺一不可。
能力表直接写在仓库文档里，每行三列：API 或组件名、要求的基础库版本、降级方式。新 API 进代码前先登记，没登记的不允许直接调用——这条提交规范比口头约定有效。
降级方案分三档：隐藏入口（低版本用户不展示新功能）、提示升级（告知需更新微信）、替身实现（用老 API 拼简化版）。涉及渲染层变化时对照 Skyline 迁移口径 做双渲染层回归；涉及懒加载策略时参考 懒加载注入说明，别让降级分支自己先挂了。
四、落地步骤：五步接进现有项目
结论句：接入顺序是「先盘点、再封装、后降级」，最后用低版本真机验收收口。
- 盘点能力：列出项目用到的新 API 与组件，逐条查文档登记要求的基础库版本，形成能力表。
- 封装判断：统一封装版本比较与能力检测函数，业务代码只问「支不支持」，不自己解析版本号。
- 补降级分支：每个新能力对应一档降级：隐藏、提示升级或替身实现，禁止「无响应」这种默认行为。
- 设置最低基础库：在小程序后台配置最低基础库版本，低于该版本的诉求由降级方案承接。
- 低版本真机回归：找一台停在最低基础库的真机过一遍主路径，确认降级分支可用、无白屏无报错。
五、升级提示与回归验收
结论句：升级提示要给商家留文案口，回归要写进提审前用例，两项都不做等于降级白做。
升级提示属于运营动作：商家提供「请把微信更新到最新版后使用」这类统一文案，开发按触发时机展示，只做一次。配合 更新管理器用法 处理小程序自身更新：用户更新微信解决基础库，小程序静默更新解决自身版本。
| 验收项 | 达标口径 | 常见错误 |
|---|---|---|
| 能力表覆盖 | 每个新 API 都有版本要求与降级方式 | 新 API 直接上线，无任何登记 |
| 降级可达 | 低版本真机走通全部降级分支 | 只在最新版本上测，降级从未被执行过 |
| 升级提示 | 一次触发、文案统一、可跳过 | 反复弹窗或文案含内部术语 |
六、避坑清单
这四条坑都和「想当然」有关：版本比较、环境假设、字段误用、过度采集。
- 别用字符串直接比版本：「2.9」和「2.10」按字符串比会得出错误结论，必须逐段转数字。
- 别假设所有宿主行为一致：host 字段就是用来区分环境的，跨环境差异要在能力表里体现。
- 别把 getAppBaseInfo 当设备信息：它不含品牌与系统版本，硬件信息另走设备信息接口。
- 别为判断版本而过度采集：只读需要的字段，与隐私口径无关的能力不要顺手全读一遍。
七、常见问题 FAQ
这个和 GEO 地理位置配置有关系吗？
没有关系。GEO 指小程序 GEO 地理位置配置——门店地址、经纬度、服务类目，决定「附近」检索的展示；基础库版本判断是代码层的兼容处理，两者不在一个配置面上。定位类 API 的版本要求倒是可以登记进能力表。
最低基础库设置得越高越好吗？
不是。设得高，旧微信用户直接进不来或功能缺失，损失存量订单；设得低，降级方案就得多写。口径是：先统计用户基础库分布，把最低版本设在覆盖绝大多数用户的临界点上。
商家需要懂这些字段吗？
不需要记字段，但要知道结论：升级提示文案由商家定，低版本用户体验由商家拍板（隐藏还是提示）。开发负责把技术判断翻译成这两个可选项。
能力表谁来维护？
开发维护、随代码一起提交。新 API 进代码前先登记版本要求与降级方式，评审时把「没登记」当待办打回，成本最低。
低版本真机不好找怎么办？
优先用开发者工具的基础库版本切换模拟，覆盖九成逻辑；关键路径（支付、登录、渲染层）再借一台停留在最低基础库的真机回归，两者缺一不可。
