用户发来一句页面打不开白屏你本地怎么刷新都正常排查半天代码没毛病——最后发现对方微信是半年前的老版本基础库还停在 2.14而你写的接口是 3.x 才有的。这种事在小程序开发里出现的频率比大多数人想象的高得多。微信小程序基础库就是客户端里那套负责跑你代码的运行环境它决定了 wx.* 接口有没有、组件属性灵不灵、渲染引擎怎么表现。它跟着微信客户端走不由你发布却实实在在决定你的页面在用户手机上活不活得下来。这篇内容就围绕基础库是什么、版本号怎么对应、能在哪几个地方改、改了之后代码要怎么跟着调整来讲适合刚接手小程序项目的新人也适合被低版本兼容问题折磨过的老手。1. 基础库不是依赖包是装在客户端里的运行环境很多人第一次听到基础库三个字下意识会当成 npm 依赖那样理解以为可以在 package.json 里指定版本、锁版本、升级版本。这个理解方向是错的而且错得很关键因为它会直接导致你对线上问题失去判断力。1.1 你的代码和基础库之间的分工边界基础库承担的是底座角色。你写的 pages、components、业务逻辑本质上是跑在基础库提供的运行环境里的脚本。具体来说基础库负责这几件事把 JS 逻辑和渲染层之间的通信桥接起来实现 view、scroll-view、picker、map 这些内置组件的渲染行为实现 wx.* 系列接口请求、存储、文件系统、蓝牙、相机、支付等以及调度页面生命周期、处理页面栈管理。打个不太严谨但很好用的比方基础库像游戏引擎本体你写的小程序代码像跑在引擎上的脚本模组。引擎版本决定了脚本能调用哪些接口。你把脚本升级、用了新引擎才有的接口拿到老引擎上跑就是直接报错反过来引擎升级了老脚本通常还能跑只是有些行为可能悄悄变了。这个不对称性就是所有兼容问题的根源。1.2 客户端版本、基础库版本、开发者工具版本三个号别搞混实际项目里最常混的三个版本号我列个表对照一下版本类型长什么样谁决定它影响范围微信客户端版本8.0.xx用户在应用商店更新决定手机上能用的基础库上限基础库版本2.xx.x / 3.x.x随客户端内置下发决定 wx.* 接口和组件能力开发者工具版本1.06.xxxxxx你自己在官网下载安装只决定工具本身的调试能力它们之间的关系是新的基础库版本一般跟随某次微信客户端版本发布用户把微信更新到够新的版本才能拿到新的基础库。官方有一张客户端与基础库的对照表会随版本迭代更新。这里我要提醒一句不要靠记忆去背这张表里的具体数字我见过太多人拿着一年前的对照关系做判断结果全错。要用的时候直接查官方文档最新版本。1.3 为什么同一个接口在不同手机上表现完全不同想清楚下面这几条链路你就能预判大部分兼容问题用户微信版本旧基础库低你调的接口在这个版本里根本不存在运行时报xxx is not a function后台把最低基础库版本设得比较低用户能正常进小程序但页面里用到的较新能力直接静默失效不报错也不显示你在开发者工具里把调试基础库切到了最新本地一路顺畅线上大量老版本用户打开就是白屏安卓厂商渠道的微信版本更新滞后同一个机型不同渠道装的微信基础库可能差好几个版本。第二条是最阴的因为它不报错。组件上的新属性、wxml 里的新写法在老基础库上通常不会抛异常只是不生效。你如果只在控制台找报错永远找不到原因只能靠肉眼比对页面表现。2. 能改基础库版本的四个入口作用范围天差地别更改基础库这句话在小程序生态里其实对应四个完全不同的操作。很多人搞不清它们的作用范围改了一个以为线上就生效了或者反过来担心改一下就把线上搞崩了。这四个入口我一个个拆。2.1 开发者工具的调试基础库只影响你这台电脑路径在开发者工具右上角详情面板里找本地设置或调试基础库下拉框。这里选中的版本只决定当前这台机器、当前这个工具窗口里运行代码时用的基础库。它不会写进代码不会提交到版本库也不会影响任何其他同事和任何线上用户。它的核心用途只有一个复现低版本问题。当有人反馈我这个手机上打开有问题你第一件事就是把自己的调试基础库切到跟他接近的版本看能不能复现。能复现问题基本就锁定在版本兼容上不能复现再往机型、网络、数据方向查。注意真机预览和真机调试时用的是手机上的真实基础库不是你在工具里选的那个。所以工具里切低版本能跑通不代表真机低版本就能跑通两个环节都要测。2.2 project.config.json 里的 libVersion团队协作的锚点项目根目录下有个 project.config.json里面有个libVersion字段它决定开发者工具打开这个项目时默认使用哪个基础库。这个文件是跟着代码进版本库的所以它的真正价值是统一团队的调试环境。我踩过这个坑一个三人小组开发同一个项目A 的 libVersion 是 3.xB 的没配、用工具默认最新C 的因为之前切过手动调成了 2.x。结果同一个页面三个人看到三种表现光排查到底谁的环境是对的就浪费了半天。后来我们把 libVersion 显式写进 project.config.json 并提交这个问题就再没出现过。再强调一遍这个字段同样只影响开发工具不影响线上。它管的是我们开发时看到什么不是用户看到什么。2.3 小程序后台的最低基础库版本唯一影响线上的开关这是四个入口里唯一真正影响线上用户的也是唯一需要慎重对待的。位置在公众平台后台设置里的基本设置相关区域可以设置最低基础库版本。菜单名称在不同时期可能微调以你实际看到的为准。它的工作机制是你设了一个值之后客户端会做一次检查低于这个版本的微信打开小程序会被提示更新微信。换句话说抬高这个值等于主动放弃一部分用户。这个操作不可逆也没有只对一半用户生效这种精细控制所以它是一个业务决策不是纯技术决策。2.4 uniapp、HBuilderX 发行链条里的版本声明用 uniapp 或 HBuilderX 的团队情况要绕一层。你的工程里没有手写的 project.config.json它是发行时生成的。你可以在 manifest.json 的mp-weixin节点里配置libVersion发行时会被写进生成的 project.config.json 里。所以 uniapp 项目里改基础库版本实际是两件事改 manifest.json 让开发环境和产物的调试版本一致以及去后台改最低基础库版本控制线上门槛。我建议每次发行后用文本编辑器打开 dist 目录下生成的 project.config.json确认 libVersion 真的是你预期的值别只信配置文件。入口影响谁影响线上典型用途工具调试基础库本机当前窗口否复现低版本问题project.config.json团队开发环境否统一调试版本后台最低基础库版本所有线上用户是抬高准入门槛manifest.jsonuniapp发行产物间接同步工程配置3. 版本不一致时代码层面怎么写出兼容逻辑定位到版本问题只是第一步真正的工程量在于让同一份代码在老版本和新版本上都能正常工作。这块有三套手法我用下来最稳的组合是运行时探测为主 构建时条件编译为辅。3.1 wx.canIUse三个层次的能力探测wx.canIUse返回布尔值它能在三个层次上做判断判断接口和返回值字段wx.canIUse(getSystemInfoSync.return.screenWidth)判断接口的参数wx.canIUse(showToast.object.image)判断组件和组件属性wx.canIUse(button.open-type.contact)我建议只在影响主流程的地方用它。有些人写代码恨不得每个接口都包一层 canIUse结果是代码里全是判断分支可读性极差维护成本比兼容问题本身还高。判断的优先级应该是不用这个能力页面就白屏或功能不可用必须判只是体验上的锦上添花直接降级或不做。3.2 版本号比较必须用数值比较不能用字符串这是个特别隐蔽的坑。基础库版本号是3.10.0这种多段数字如果你直接拿字符串比大小3.10.0 3.9.0会返回 true因为字符1小于9。判断逻辑直接反了而且反得悄无声息。正确做法是拆成数组逐段转数字比较function compareVersion(v1, v2) { const a1 String(v1).split(.) const a2 String(v2).split(.) const len Math.max(a1.length, a2.length) while (a1.length len) a1.push(0) while (a2.length len) a2.push(0) for (let i 0; i len; i) { const n1 parseInt(a1[i], 10) || 0 const n2 parseInt(a2[i], 10) || 0 if (n1 n2) return 1 if (n1 n2) return -1 } return 0 } // 用法 const info wx.getAppBaseInfo ? wx.getAppBaseInfo() : wx.getSystemInfoSync() if (compareVersion(info.SDKVersion, 2.20.0) 0) { // 走新路径 } else { // 走降级路径 }3.3 接口拆分后的兼容写法新版基础库把原来一个大而全的系统信息接口拆成了几个更细的接口分别返回应用信息、窗口信息、设备信息。老基础库上只有合并的那个。写兼容函数是最省事的function getEnvInfo() { if (wx.getWindowInfo wx.getDeviceInfo wx.getAppBaseInfo) { return { window: wx.getWindowInfo(), device: wx.getDeviceInfo(), app: wx.getAppBaseInfo() } } const legacy wx.getSystemInfoSync() return { window: { statusBarHeight: legacy.statusBarHeight, windowWidth: legacy.windowWidth, windowHeight: legacy.windowHeight, safeArea: legacy.safeArea }, device: { platform: legacy.platform, brand: legacy.brand }, app: { SDKVersion: legacy.SDKVersion, version: legacy.version } } }这个函数我一般放在 app.js 的 onLaunch 里调一次结果挂到全局页面里直接读。别在每一个页面里重复调用那既浪费性能也让代码到处散落版本判断逻辑。3.4 uni-app 里的条件编译uni-app 提供构建期的条件编译语法是// #ifdef MP-WEIXIN到// #endif之间。它解决的是只想在微信端执行某段代码的问题不是版本差异问题。版本差异还是得靠上面的运行时判断。这两者经常被混用。我的划分标准很简单跨平台差异用条件编译同一平台内的版本差异用运行时判断。别试图用条件编译去解决版本问题它做不到因为编译发生时你根本不知道用户的基础库是几。4. 版本差异最容易炸的几类真实场景理论讲完说几个我在项目里真真切切被卡过的场景。这些问题的共同点是报错信息模糊搜索也搜不到明确答案只能靠对基础库和渲染机制的理解去推。4.1 iOS 和安卓的滚动、吸附行为差异同一份 wxmliOS 上滑得顺滑某些安卓机型上卡顿甚至滑动失效这是最容易让人怀疑人生的场景。原因一般出在滚动容器的选择上页面级滚动和 scroll-view 内部滚动混在一起用加上不同系统内核对滚动优化属性的支持程度不同表现就散了。我的处理原则是如果一个区域需要独立滚动就明确用 scroll-view 承担不要让页面本身滚动和内部滚动嵌套。scroll-view 上有个增强滚动的属性需要较新的基础库才生效老版本上写了不报错也不起作用——正好是前面说的静默失效。所以要做滚动体验优化的先用 canIUse 判断再决定加不加这个属性。注意位置吸附这类 CSS 属性同样受内核和基础库版本影响在低版本设备上可能完全没效果。凡是靠它做关键布局的都要准备一个不依赖它的兜底方案。4.2 顶部导航栏高度和胶囊按钮的位置计算自定义导航栏几乎是每个小程序的必修课而高度算错导致标题被胶囊按钮挡住也是高频事故。正确的高度计算公式是导航栏高度 (胶囊按钮.top - 状态栏高度) * 2 胶囊按钮.height对应代码function getNavBarHeight() { const win wx.getWindowInfo ? wx.getWindowInfo() : wx.getSystemInfoSync() const statusBarHeight win.statusBarHeight || 20 if (!wx.getMenuButtonBoundingClientRect) { // 老基础库兜底 return statusBarHeight 44 } const menu wx.getMenuButtonBoundingClientRect() if (!menu || !menu.height) return statusBarHeight 44 return (menu.top - statusBarHeight) * 2 menu.height }这里有两个点要注意。一是必须给兜底值不能假定接口一定存在二是这个计算要在页面加载时做一次并缓存不要每次渲染都算因为胶囊按钮的位置在横竖屏切换时会变需要在方向变化时重新取。4.3 scroll-view 里嵌日期选择器弹层定位跑偏这个问题我在好几个项目里都遇到过典型的现场是日期选择器放在一个可滚动的表单容器里点开之后弹层出现在完全不相干的位置甚至被裁掉一半。原因通常有两层弹层组件内部用的是固定定位而它的祖先元素上存在位移变换导致固定定位的参考系变成了那个祖先而不是视口再加上滚动容器本身的裁剪行为弹层就被切了。解法有几个方向按优先级排把弹层的 DOM 结构挂到页面最外层而不是留在滚动容器内。较新的基础库提供了把节点渲染到根节点之外的组件能力用了它就一劳永逸但同样要先判断基础库是否支持如果不能用上面的方案就退一步把选择器放在滚动容器外面滚动区域只放展示点击时才唤起选择器检查滚动容器及其祖先上有没有位移变换、透视、滤镜之类的属性有就尽量移掉这些属性会改变固定定位的参考系。4.4 本地文件路径常量的正确用法有个常量表示小程序的用户文件目录它是一个字符串常量不是函数写成wx.env.USER_DATA_PATH()会直接报错。正确用法是直接当字符串拼路径const fm wx.getFileSystemManager() const filePath ${wx.env.USER_DATA_PATH}/temp_export.txt fm.writeFileSync(filePath, hello, utf8)用它的场景一般是导出文件、缓存图片、生成临时数据。这里有两个实际经验一是这个目录的容量有上限写入前最好先估算剩余空间定期清理二是文件系统相关接口在不同基础库版本上的能力集不完全一致如果你要做删除、重命名、读取目录这类操作先做能力判断再调用别假定全都存在。5. 把最低基础库版本安全抬上去的完整流程讲完兼容代码回到那个唯一影响线上的开关。抬高最低基础库版本是个纯收益诱惑很大的操作——可以少写一堆兼容代码可以用上新能力。但操作不当代价是真金白银的用户流失所以我把它当一次小型发版来做。5.1 先读数据别拍脑袋定版本后台的统计模块里能看到基础库版本分布各版本的用户占比一目了然。我建议你按这个顺序做判断先看当前覆盖率。如果你现在设的最低版本已经覆盖了 99% 以上那基本没有抬升空间别折腾再看目标版本能带来什么。如果只是为了用一个体验优化类能力抬版本不值最后算被挡比例。把所有低于目标版本的占比加起来就是会被提示升级的用户比例。我的经验阈值是覆盖率低于 98% 就别抬。98% 到 99.5% 之间可以评估但要做好回归测试。高于 99.5% 且确实有硬需求才考虑动手。这个阈值不是硬标准取决于你的业务场景但核心思路是别为了省一点开发量去换用户流失。5.2 抬版本之前的必做动作直接抬版本然后等线上报错是最糟的顺序。正确顺序是先把兼容代码补齐让旧版本用户也能用再考虑抬。具体流程我整理成一张检查表检查项具体做法通过标准版本号数值比较全局搜索所有版本比较逻辑全部用数值比较函数接口存在性判断逐个核对新接口调用点关键路径全部有降级分支组件属性兼容核对 wxml 里的新属性不支持的版本有替代方案工具多版本跑测在工具里从最低版本逐级切换核心路径全通过真机验证用接近目标版本的旧手机实测无明显异常线上埋点上报用户实际基础库版本能拿到真实分布数据5.3 灰度抬高与回退预案如果你的平台支持分阶段设置就分批抬观察一到两周。观察的重点指标有三个页面白屏率、接口报错率、用户打开后的流失率。前两个能直接从错误监控里看第三个需要自己埋点。回退预案也必须提前想好。抬高版本之后如果再调低理论上不会立刻恢复已流失用户的使用但至少能止住新的流失。所以回退动作要快一旦发现报错率显著上升立刻调回去先止血再分析。6. 几个项目做完之后我自己沉淀下来的习惯最后说几条纯粹个人经验都是被坑出来的。第一条是我现在写任何新项目第一件事就是在 app.js 里把基础库版本取出来做一次统一上报带上机型、系统、客户端版本。不为了别的就为了出问题时能快速回答用户到底在什么环境上。没有这个数据所有兼容问题的排查都是瞎猜。第二条是团队协作时把 project.config.json 明确纳入版本管理并且约定任何人不得在本地随意改调试基础库而不通知其他人。这个小约定省下来的沟通成本比我预想的高得多。第三条是不要写防御性过度的兼容代码。曾经有个项目我为了兼容一个占比不到 0.5% 的老版本写了三层降级分支结果那部分代码在后续两年里成了维护重灾区每次改动都要考虑三套路径。后来我们直接抬了最低版本把它砍掉代码量少了三分之一可读性也上来了。兼容是有成本的成本要跟收益比。第四条是每次调整最低基础库版本都在项目文档里记一句日期、从哪个版本抬到哪个版本、原因、当时的覆盖率。这行字看起来没什么但半年后有人问我们为什么不能低于 2.20的时候你能立刻答上来而不是所有人一起回忆。
微信小程序基础库版本兼容与最低版本设置指南
用户发来一句页面打不开白屏你本地怎么刷新都正常排查半天代码没毛病——最后发现对方微信是半年前的老版本基础库还停在 2.14而你写的接口是 3.x 才有的。这种事在小程序开发里出现的频率比大多数人想象的高得多。微信小程序基础库就是客户端里那套负责跑你代码的运行环境它决定了 wx.* 接口有没有、组件属性灵不灵、渲染引擎怎么表现。它跟着微信客户端走不由你发布却实实在在决定你的页面在用户手机上活不活得下来。这篇内容就围绕基础库是什么、版本号怎么对应、能在哪几个地方改、改了之后代码要怎么跟着调整来讲适合刚接手小程序项目的新人也适合被低版本兼容问题折磨过的老手。1. 基础库不是依赖包是装在客户端里的运行环境很多人第一次听到基础库三个字下意识会当成 npm 依赖那样理解以为可以在 package.json 里指定版本、锁版本、升级版本。这个理解方向是错的而且错得很关键因为它会直接导致你对线上问题失去判断力。1.1 你的代码和基础库之间的分工边界基础库承担的是底座角色。你写的 pages、components、业务逻辑本质上是跑在基础库提供的运行环境里的脚本。具体来说基础库负责这几件事把 JS 逻辑和渲染层之间的通信桥接起来实现 view、scroll-view、picker、map 这些内置组件的渲染行为实现 wx.* 系列接口请求、存储、文件系统、蓝牙、相机、支付等以及调度页面生命周期、处理页面栈管理。打个不太严谨但很好用的比方基础库像游戏引擎本体你写的小程序代码像跑在引擎上的脚本模组。引擎版本决定了脚本能调用哪些接口。你把脚本升级、用了新引擎才有的接口拿到老引擎上跑就是直接报错反过来引擎升级了老脚本通常还能跑只是有些行为可能悄悄变了。这个不对称性就是所有兼容问题的根源。1.2 客户端版本、基础库版本、开发者工具版本三个号别搞混实际项目里最常混的三个版本号我列个表对照一下版本类型长什么样谁决定它影响范围微信客户端版本8.0.xx用户在应用商店更新决定手机上能用的基础库上限基础库版本2.xx.x / 3.x.x随客户端内置下发决定 wx.* 接口和组件能力开发者工具版本1.06.xxxxxx你自己在官网下载安装只决定工具本身的调试能力它们之间的关系是新的基础库版本一般跟随某次微信客户端版本发布用户把微信更新到够新的版本才能拿到新的基础库。官方有一张客户端与基础库的对照表会随版本迭代更新。这里我要提醒一句不要靠记忆去背这张表里的具体数字我见过太多人拿着一年前的对照关系做判断结果全错。要用的时候直接查官方文档最新版本。1.3 为什么同一个接口在不同手机上表现完全不同想清楚下面这几条链路你就能预判大部分兼容问题用户微信版本旧基础库低你调的接口在这个版本里根本不存在运行时报xxx is not a function后台把最低基础库版本设得比较低用户能正常进小程序但页面里用到的较新能力直接静默失效不报错也不显示你在开发者工具里把调试基础库切到了最新本地一路顺畅线上大量老版本用户打开就是白屏安卓厂商渠道的微信版本更新滞后同一个机型不同渠道装的微信基础库可能差好几个版本。第二条是最阴的因为它不报错。组件上的新属性、wxml 里的新写法在老基础库上通常不会抛异常只是不生效。你如果只在控制台找报错永远找不到原因只能靠肉眼比对页面表现。2. 能改基础库版本的四个入口作用范围天差地别更改基础库这句话在小程序生态里其实对应四个完全不同的操作。很多人搞不清它们的作用范围改了一个以为线上就生效了或者反过来担心改一下就把线上搞崩了。这四个入口我一个个拆。2.1 开发者工具的调试基础库只影响你这台电脑路径在开发者工具右上角详情面板里找本地设置或调试基础库下拉框。这里选中的版本只决定当前这台机器、当前这个工具窗口里运行代码时用的基础库。它不会写进代码不会提交到版本库也不会影响任何其他同事和任何线上用户。它的核心用途只有一个复现低版本问题。当有人反馈我这个手机上打开有问题你第一件事就是把自己的调试基础库切到跟他接近的版本看能不能复现。能复现问题基本就锁定在版本兼容上不能复现再往机型、网络、数据方向查。注意真机预览和真机调试时用的是手机上的真实基础库不是你在工具里选的那个。所以工具里切低版本能跑通不代表真机低版本就能跑通两个环节都要测。2.2 project.config.json 里的 libVersion团队协作的锚点项目根目录下有个 project.config.json里面有个libVersion字段它决定开发者工具打开这个项目时默认使用哪个基础库。这个文件是跟着代码进版本库的所以它的真正价值是统一团队的调试环境。我踩过这个坑一个三人小组开发同一个项目A 的 libVersion 是 3.xB 的没配、用工具默认最新C 的因为之前切过手动调成了 2.x。结果同一个页面三个人看到三种表现光排查到底谁的环境是对的就浪费了半天。后来我们把 libVersion 显式写进 project.config.json 并提交这个问题就再没出现过。再强调一遍这个字段同样只影响开发工具不影响线上。它管的是我们开发时看到什么不是用户看到什么。2.3 小程序后台的最低基础库版本唯一影响线上的开关这是四个入口里唯一真正影响线上用户的也是唯一需要慎重对待的。位置在公众平台后台设置里的基本设置相关区域可以设置最低基础库版本。菜单名称在不同时期可能微调以你实际看到的为准。它的工作机制是你设了一个值之后客户端会做一次检查低于这个版本的微信打开小程序会被提示更新微信。换句话说抬高这个值等于主动放弃一部分用户。这个操作不可逆也没有只对一半用户生效这种精细控制所以它是一个业务决策不是纯技术决策。2.4 uniapp、HBuilderX 发行链条里的版本声明用 uniapp 或 HBuilderX 的团队情况要绕一层。你的工程里没有手写的 project.config.json它是发行时生成的。你可以在 manifest.json 的mp-weixin节点里配置libVersion发行时会被写进生成的 project.config.json 里。所以 uniapp 项目里改基础库版本实际是两件事改 manifest.json 让开发环境和产物的调试版本一致以及去后台改最低基础库版本控制线上门槛。我建议每次发行后用文本编辑器打开 dist 目录下生成的 project.config.json确认 libVersion 真的是你预期的值别只信配置文件。入口影响谁影响线上典型用途工具调试基础库本机当前窗口否复现低版本问题project.config.json团队开发环境否统一调试版本后台最低基础库版本所有线上用户是抬高准入门槛manifest.jsonuniapp发行产物间接同步工程配置3. 版本不一致时代码层面怎么写出兼容逻辑定位到版本问题只是第一步真正的工程量在于让同一份代码在老版本和新版本上都能正常工作。这块有三套手法我用下来最稳的组合是运行时探测为主 构建时条件编译为辅。3.1 wx.canIUse三个层次的能力探测wx.canIUse返回布尔值它能在三个层次上做判断判断接口和返回值字段wx.canIUse(getSystemInfoSync.return.screenWidth)判断接口的参数wx.canIUse(showToast.object.image)判断组件和组件属性wx.canIUse(button.open-type.contact)我建议只在影响主流程的地方用它。有些人写代码恨不得每个接口都包一层 canIUse结果是代码里全是判断分支可读性极差维护成本比兼容问题本身还高。判断的优先级应该是不用这个能力页面就白屏或功能不可用必须判只是体验上的锦上添花直接降级或不做。3.2 版本号比较必须用数值比较不能用字符串这是个特别隐蔽的坑。基础库版本号是3.10.0这种多段数字如果你直接拿字符串比大小3.10.0 3.9.0会返回 true因为字符1小于9。判断逻辑直接反了而且反得悄无声息。正确做法是拆成数组逐段转数字比较function compareVersion(v1, v2) { const a1 String(v1).split(.) const a2 String(v2).split(.) const len Math.max(a1.length, a2.length) while (a1.length len) a1.push(0) while (a2.length len) a2.push(0) for (let i 0; i len; i) { const n1 parseInt(a1[i], 10) || 0 const n2 parseInt(a2[i], 10) || 0 if (n1 n2) return 1 if (n1 n2) return -1 } return 0 } // 用法 const info wx.getAppBaseInfo ? wx.getAppBaseInfo() : wx.getSystemInfoSync() if (compareVersion(info.SDKVersion, 2.20.0) 0) { // 走新路径 } else { // 走降级路径 }3.3 接口拆分后的兼容写法新版基础库把原来一个大而全的系统信息接口拆成了几个更细的接口分别返回应用信息、窗口信息、设备信息。老基础库上只有合并的那个。写兼容函数是最省事的function getEnvInfo() { if (wx.getWindowInfo wx.getDeviceInfo wx.getAppBaseInfo) { return { window: wx.getWindowInfo(), device: wx.getDeviceInfo(), app: wx.getAppBaseInfo() } } const legacy wx.getSystemInfoSync() return { window: { statusBarHeight: legacy.statusBarHeight, windowWidth: legacy.windowWidth, windowHeight: legacy.windowHeight, safeArea: legacy.safeArea }, device: { platform: legacy.platform, brand: legacy.brand }, app: { SDKVersion: legacy.SDKVersion, version: legacy.version } } }这个函数我一般放在 app.js 的 onLaunch 里调一次结果挂到全局页面里直接读。别在每一个页面里重复调用那既浪费性能也让代码到处散落版本判断逻辑。3.4 uni-app 里的条件编译uni-app 提供构建期的条件编译语法是// #ifdef MP-WEIXIN到// #endif之间。它解决的是只想在微信端执行某段代码的问题不是版本差异问题。版本差异还是得靠上面的运行时判断。这两者经常被混用。我的划分标准很简单跨平台差异用条件编译同一平台内的版本差异用运行时判断。别试图用条件编译去解决版本问题它做不到因为编译发生时你根本不知道用户的基础库是几。4. 版本差异最容易炸的几类真实场景理论讲完说几个我在项目里真真切切被卡过的场景。这些问题的共同点是报错信息模糊搜索也搜不到明确答案只能靠对基础库和渲染机制的理解去推。4.1 iOS 和安卓的滚动、吸附行为差异同一份 wxmliOS 上滑得顺滑某些安卓机型上卡顿甚至滑动失效这是最容易让人怀疑人生的场景。原因一般出在滚动容器的选择上页面级滚动和 scroll-view 内部滚动混在一起用加上不同系统内核对滚动优化属性的支持程度不同表现就散了。我的处理原则是如果一个区域需要独立滚动就明确用 scroll-view 承担不要让页面本身滚动和内部滚动嵌套。scroll-view 上有个增强滚动的属性需要较新的基础库才生效老版本上写了不报错也不起作用——正好是前面说的静默失效。所以要做滚动体验优化的先用 canIUse 判断再决定加不加这个属性。注意位置吸附这类 CSS 属性同样受内核和基础库版本影响在低版本设备上可能完全没效果。凡是靠它做关键布局的都要准备一个不依赖它的兜底方案。4.2 顶部导航栏高度和胶囊按钮的位置计算自定义导航栏几乎是每个小程序的必修课而高度算错导致标题被胶囊按钮挡住也是高频事故。正确的高度计算公式是导航栏高度 (胶囊按钮.top - 状态栏高度) * 2 胶囊按钮.height对应代码function getNavBarHeight() { const win wx.getWindowInfo ? wx.getWindowInfo() : wx.getSystemInfoSync() const statusBarHeight win.statusBarHeight || 20 if (!wx.getMenuButtonBoundingClientRect) { // 老基础库兜底 return statusBarHeight 44 } const menu wx.getMenuButtonBoundingClientRect() if (!menu || !menu.height) return statusBarHeight 44 return (menu.top - statusBarHeight) * 2 menu.height }这里有两个点要注意。一是必须给兜底值不能假定接口一定存在二是这个计算要在页面加载时做一次并缓存不要每次渲染都算因为胶囊按钮的位置在横竖屏切换时会变需要在方向变化时重新取。4.3 scroll-view 里嵌日期选择器弹层定位跑偏这个问题我在好几个项目里都遇到过典型的现场是日期选择器放在一个可滚动的表单容器里点开之后弹层出现在完全不相干的位置甚至被裁掉一半。原因通常有两层弹层组件内部用的是固定定位而它的祖先元素上存在位移变换导致固定定位的参考系变成了那个祖先而不是视口再加上滚动容器本身的裁剪行为弹层就被切了。解法有几个方向按优先级排把弹层的 DOM 结构挂到页面最外层而不是留在滚动容器内。较新的基础库提供了把节点渲染到根节点之外的组件能力用了它就一劳永逸但同样要先判断基础库是否支持如果不能用上面的方案就退一步把选择器放在滚动容器外面滚动区域只放展示点击时才唤起选择器检查滚动容器及其祖先上有没有位移变换、透视、滤镜之类的属性有就尽量移掉这些属性会改变固定定位的参考系。4.4 本地文件路径常量的正确用法有个常量表示小程序的用户文件目录它是一个字符串常量不是函数写成wx.env.USER_DATA_PATH()会直接报错。正确用法是直接当字符串拼路径const fm wx.getFileSystemManager() const filePath ${wx.env.USER_DATA_PATH}/temp_export.txt fm.writeFileSync(filePath, hello, utf8)用它的场景一般是导出文件、缓存图片、生成临时数据。这里有两个实际经验一是这个目录的容量有上限写入前最好先估算剩余空间定期清理二是文件系统相关接口在不同基础库版本上的能力集不完全一致如果你要做删除、重命名、读取目录这类操作先做能力判断再调用别假定全都存在。5. 把最低基础库版本安全抬上去的完整流程讲完兼容代码回到那个唯一影响线上的开关。抬高最低基础库版本是个纯收益诱惑很大的操作——可以少写一堆兼容代码可以用上新能力。但操作不当代价是真金白银的用户流失所以我把它当一次小型发版来做。5.1 先读数据别拍脑袋定版本后台的统计模块里能看到基础库版本分布各版本的用户占比一目了然。我建议你按这个顺序做判断先看当前覆盖率。如果你现在设的最低版本已经覆盖了 99% 以上那基本没有抬升空间别折腾再看目标版本能带来什么。如果只是为了用一个体验优化类能力抬版本不值最后算被挡比例。把所有低于目标版本的占比加起来就是会被提示升级的用户比例。我的经验阈值是覆盖率低于 98% 就别抬。98% 到 99.5% 之间可以评估但要做好回归测试。高于 99.5% 且确实有硬需求才考虑动手。这个阈值不是硬标准取决于你的业务场景但核心思路是别为了省一点开发量去换用户流失。5.2 抬版本之前的必做动作直接抬版本然后等线上报错是最糟的顺序。正确顺序是先把兼容代码补齐让旧版本用户也能用再考虑抬。具体流程我整理成一张检查表检查项具体做法通过标准版本号数值比较全局搜索所有版本比较逻辑全部用数值比较函数接口存在性判断逐个核对新接口调用点关键路径全部有降级分支组件属性兼容核对 wxml 里的新属性不支持的版本有替代方案工具多版本跑测在工具里从最低版本逐级切换核心路径全通过真机验证用接近目标版本的旧手机实测无明显异常线上埋点上报用户实际基础库版本能拿到真实分布数据5.3 灰度抬高与回退预案如果你的平台支持分阶段设置就分批抬观察一到两周。观察的重点指标有三个页面白屏率、接口报错率、用户打开后的流失率。前两个能直接从错误监控里看第三个需要自己埋点。回退预案也必须提前想好。抬高版本之后如果再调低理论上不会立刻恢复已流失用户的使用但至少能止住新的流失。所以回退动作要快一旦发现报错率显著上升立刻调回去先止血再分析。6. 几个项目做完之后我自己沉淀下来的习惯最后说几条纯粹个人经验都是被坑出来的。第一条是我现在写任何新项目第一件事就是在 app.js 里把基础库版本取出来做一次统一上报带上机型、系统、客户端版本。不为了别的就为了出问题时能快速回答用户到底在什么环境上。没有这个数据所有兼容问题的排查都是瞎猜。第二条是团队协作时把 project.config.json 明确纳入版本管理并且约定任何人不得在本地随意改调试基础库而不通知其他人。这个小约定省下来的沟通成本比我预想的高得多。第三条是不要写防御性过度的兼容代码。曾经有个项目我为了兼容一个占比不到 0.5% 的老版本写了三层降级分支结果那部分代码在后续两年里成了维护重灾区每次改动都要考虑三套路径。后来我们直接抬了最低版本把它砍掉代码量少了三分之一可读性也上来了。兼容是有成本的成本要跟收益比。第四条是每次调整最低基础库版本都在项目文档里记一句日期、从哪个版本抬到哪个版本、原因、当时的覆盖率。这行字看起来没什么但半年后有人问我们为什么不能低于 2.20的时候你能立刻答上来而不是所有人一起回忆。
