企业官网建设流程全解析

用户发来一句"页面打不开，白屏"，你本地怎么刷新都正常，排查半天代码没毛病——最后发现对方微信是半年前的老版本，基础库还停在 2.14，而你写的接口是 3.x 才有的。这种事在小程序开发里出现的频率，比大多数人想象的高得多。微信小程序基础库，就是客户端里那套负责跑你代码的运行环境，它决定了 wx.* 接口有没有、组件属性灵不灵、渲染引擎怎么表现。它跟着微信客户端走，不由你发布，却实实在在决定你的页面在用户手机上活不活得下来。这篇内容就围绕基础库是什么、版本号怎么对应、能在哪几个地方改、改了之后代码要怎么跟着调整来讲，适合刚接手小程序项目的新人，也适合被低版本兼容问题折磨过的老手。

1. 基础库不是依赖包，是装在客户端里的运行环境

很多人第一次听到"基础库"三个字，下意识会当成 npm 依赖那样理解，以为可以在 package.json 里指定版本、锁版本、升级版本。这个理解方向是错的，而且错得很关键，因为它会直接导致你对线上问题失去判断力。

1.1 你的代码和基础库之间的分工边界

基础库承担的是"底座"角色。你写的 pages、components、业务逻辑，本质上是跑在基础库提供的运行环境里的脚本。具体来说，基础库负责这几件事：把 JS 逻辑和渲染层之间的通信桥接起来，实现 view、scroll-view、picker、map 这些内置组件的渲染行为，实现 wx.* 系列接口（请求、存储、文件系统、蓝牙、相机、支付等），以及调度页面生命周期、处理页面栈管理。

打个不太严谨但很好用的比方：基础库像游戏引擎本体，你写的小程序代码像跑在引擎上的脚本模组。引擎版本决定了脚本能调用哪些接口。你把脚本升级、用了新引擎才有的接口，拿到老引擎上跑，就是直接报错；反过来，引擎升级了，老脚本通常还能跑，只是有些行为可能悄悄变了。这个不对称性，就是所有兼容问题的根源。

1.2 客户端版本、基础库版本、开发者工具版本，三个号别搞混

实际项目里最常混的三个版本号，我列个表对照一下：

它们之间的关系是：新的基础库版本一般跟随某次微信客户端版本发布，用户把微信更新到够新的版本，才能拿到新的基础库。官方有一张客户端与基础库的对照表，会随版本迭代更新。这里我要提醒一句，不要靠记忆去背这张表里的具体数字，我见过太多人拿着一年前的对照关系做判断，结果全错。要用的时候直接查官方文档最新版本。

1.3 为什么同一个接口在不同手机上表现完全不同

想清楚下面这几条链路，你就能预判大部分兼容问题：

• 用户微信版本旧，基础库低，你调的接口在这个版本里根本不存在，运行时报xxx is not a function；
• 后台把最低基础库版本设得比较低，用户能正常进小程序，但页面里用到的较新能力直接静默失效，不报错也不显示；
• 你在开发者工具里把调试基础库切到了最新，本地一路顺畅，线上大量老版本用户打开就是白屏；
• 安卓厂商渠道的微信版本更新滞后，同一个机型不同渠道装的微信，基础库可能差好几个版本。

第二条是最阴的，因为它不报错。组件上的新属性、wxml 里的新写法，在老基础库上通常不会抛异常，只是"不生效"。你如果只在控制台找报错，永远找不到原因，只能靠肉眼比对页面表现。

2. 能改基础库版本的四个入口，作用范围天差地别

"更改基础库"这句话，在小程序生态里其实对应四个完全不同的操作。很多人搞不清它们的作用范围，改了一个以为线上就生效了，或者反过来担心改一下就把线上搞崩了。这四个入口我一个个拆。

2.1 开发者工具的调试基础库：只影响你这台电脑

路径在开发者工具右上角"详情"面板里，找"本地设置"或"调试基础库"下拉框。这里选中的版本，只决定当前这台机器、当前这个工具窗口里运行代码时用的基础库。它不会写进代码，不会提交到版本库，也不会影响任何其他同事和任何线上用户。

它的核心用途只有一个：复现低版本问题。当有人反馈"我这个手机上打开有问题"，你第一件事就是把自己的调试基础库切到跟他接近的版本，看能不能复现。能复现，问题基本就锁定在版本兼容上；不能复现，再往机型、网络、数据方向查。

注意：真机预览和真机调试时，用的是手机上的真实基础库，不是你在工具里选的那个。所以工具里切低版本能跑通，不代表真机低版本就能跑通，两个环节都要测。

2.2 project.config.json 里的 libVersion：团队协作的锚点

项目根目录下有个 project.config.json，里面有个libVersion字段，它决定开发者工具打开这个项目时默认使用哪个基础库。这个文件是跟着代码进版本库的，所以它的真正价值是统一团队的调试环境。

我踩过这个坑：一个三人小组开发同一个项目，A 的 libVersion 是 3.x，B 的没配、用工具默认最新，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 真的是你预期的值，别只信配置文件。

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 和安卓的滚动、吸附行为差异

同一份 wxml，iOS 上滑得顺滑，某些安卓机型上卡顿甚至滑动失效，这是最容易让人怀疑人生的场景。原因一般出在滚动容器的选择上：页面级滚动和 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 先读数据，别拍脑袋定版本

后台的统计模块里能看到基础库版本分布，各版本的用户占比一目了然。我建议你按这个顺序做判断：

1. 先看当前覆盖率。如果你现在设的最低版本已经覆盖了 99% 以上，那基本没有抬升空间，别折腾；
2. 再看目标版本能带来什么。如果只是为了用一个体验优化类能力，抬版本不值；
3. 最后算被挡比例。把所有低于目标版本的占比加起来，就是会被提示升级的用户比例。

我的经验阈值是：覆盖率低于 98% 就别抬。98% 到 99.5% 之间可以评估，但要做好回归测试。高于 99.5% 且确实有硬需求，才考虑动手。这个阈值不是硬标准，取决于你的业务场景，但核心思路是别为了省一点开发量去换用户流失。

5.2 抬版本之前的必做动作

直接抬版本然后等线上报错，是最糟的顺序。正确顺序是先把兼容代码补齐，让旧版本用户也能用，再考虑抬。具体流程我整理成一张检查表：

5.3 灰度抬高与回退预案

如果你的平台支持分阶段设置，就分批抬，观察一到两周。观察的重点指标有三个：页面白屏率、接口报错率、用户打开后的流失率。前两个能直接从错误监控里看，第三个需要自己埋点。

回退预案也必须提前想好。抬高版本之后如果再调低，理论上不会立刻恢复已流失用户的使用，但至少能止住新的流失。所以回退动作要快，一旦发现报错率显著上升，立刻调回去，先止血再分析。

6. 几个项目做完之后我自己沉淀下来的习惯

最后说几条纯粹个人经验，都是被坑出来的。

第一条是我现在写任何新项目，第一件事就是在 app.js 里把基础库版本取出来做一次统一上报，带上机型、系统、客户端版本。不为了别的，就为了出问题时能快速回答"用户到底在什么环境上"。没有这个数据，所有兼容问题的排查都是瞎猜。

第二条是团队协作时把 project.config.json 明确纳入版本管理，并且约定任何人不得在本地随意改调试基础库而不通知其他人。这个小约定省下来的沟通成本，比我预想的高得多。

第三条是不要写"防御性过度"的兼容代码。曾经有个项目，我为了兼容一个占比不到 0.5% 的老版本，写了三层降级分支，结果那部分代码在后续两年里成了维护重灾区，每次改动都要考虑三套路径。后来我们直接抬了最低版本把它砍掉，代码量少了三分之一，可读性也上来了。兼容是有成本的，成本要跟收益比。

第四条是每次调整最低基础库版本，都在项目文档里记一句：日期、从哪个版本抬到哪个版本、原因、当时的覆盖率。这行字看起来没什么，但半年后有人问"我们为什么不能低于 2.20"的时候，你能立刻答上来，而不是所有人一起回忆。