问题起因

起因是内部的小程序埋点工具npm包需要新增支持曝光埋点的功能，需要借助标签添加dataset属性信息进行上报，而支付宝小程序提供的API方法my.createIntersectionObserver()在基础库2.7.0版本起才支持在IntersectionObserver.observe 回调中返回目标节点的 dataset 信息，从而满足支持曝光埋点的功能。

按照官方指南操作升级基础库，本地构建…果然报错了QAQ

于是我开始全网搜索支付宝小程序基础库2.x升级指南，结果相关文章寥寥无几，于是一头扎入支付宝小程序官方社区~

并且在这个过程中我发现了小程序基础库2.0升级通知QAQ～

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-Oup5dLAa-1669342568061)(https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/41d039151f4a4e94a88973f85da5836c~tplv-k3u1fbpfcp-zoom-1.image)]

眼看阅读量还不多，但升级基础库肯定是要升级的，那就先来升级看看吧～

什么是基础库

首先我们得弄明白什么是基础库？

官方给出的 — 基础库是负责小程序框架的加载的容器，提供小程序框架需要的标准组件和标准 API 接口。

这里有一份官方解读～

读完官方文档，结合个人理解简单总结一下：

• 可以在支付宝小程序开发者工具控制台通过 my.SDKVersion 查看当前基础库版本号
• 小程序的能力需要支付宝客户端来支撑，每一版基础库新增能力都需要特定版本以上客户端才能运行；也就是说如果更新了一个高版本基础库，且基于这个基础库提供了某个api / 新增了api入参及功能，在低版本基础库内是不支持使用这个api的 / api的新增功能的
• 当基础库准备更新时，会在客户端内进行逐步灰度直到全量发布。当用户客户端更新至最新基础库后，小程序就会运行在最新的基础库上，也就是说你的小程序运行的基础库是在逐步更新的，但在正常情况下作为小程序使用者的你是没有感知的
• 基础库支持范围有一个最低客户端版本的要求，即部分老版本客户端以后将无法更新到最新的基础库，会停留在某一历史版本，一般我们的客户端版本长时间不更新的可能性还比较小
• 关于基础库版本在支付宝客户端版本上的分布，具体看上面官方文档给出的表格吧

那么最关心的问题：如何更新基础库版本？

首先官方给出的解释：

• 基础库是根据支付宝客户端版本来更新的，没有 API 去执行更新

也就是说生产环境的基础库其实是升级了的，那么是不是基础库更新是不是完全不需要你做什么了呢？答案是否定的。

• 首先在开发环境下，需要开发者自己手动或者通过配置文件的方式切换 开发者工具 使用的基础库，支付宝小程序 IDE 从 2.9 版本开始，支持切换运行的基础库版本。若要切换基础库版本，可以点开模拟器顶部的四叶草设置菜单，点击设置，然后选择基础库版本进行模拟运行，但如果友友们还在使用1.x.x的基础库版本是不能切换的哟～

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-z3EMFxGJ-1669342568062)(https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/492da2b790754a1a8af7c6a9be1fd6e4~tplv-k3u1fbpfcp-zoom-1.image)]

• 其次在打包上传到微信后台生成体验版时，如果项目配置升级至format2以后，默认按照基础库版本2.x进行编译，但如果项目配置还是旧版本的话，借助框架管理的代码是按照基础库版本1.x编译还是按照基础库版本2.x来编译的也需要开发者自己手动在项目配置文件中指定

开发者工具升级基础库版本调试

升级基础库

参照文档本地IDE升级 — https://opendocs.alipay.com/mini/framework/lib-upgrade-v2

文档提供了两种方式：

• IDE可视化界面勾选 启用小程序基础库 2.0 构建 — 需要每次重启编译时手动勾选，不推荐
• 所以更推荐第二种写在项目代码中，在 mini.project.json 中，配置上 enableAppxNg: true 字段，不仅省去每次手动勾选，同时必须项目内代码开启才能在用jenkins打包构建并用ci自动上传时生效！

这里项目配置要写在编译之前还要区分框架等问题，但你可能刚编译就报错了…无论如何，先把代码跑起来再吧！

解决报错

由于基础库 2.x 的编译模式更为严格，因此很可能会出现各种编译报错，如下是我踩到的坑。

报错一：identifier(module) is disallowed in sjs

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-1we5ymWU-1669342568062)(https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/3c1531b761d64bb0b15a3baec59554f1~tplv-k3u1fbpfcp-zoom-1.image)]

这是因为sjs模块导入仅支持ESM模块化标准的import / export，需要手动把sjs文件内的导出后引用全部更改为ES6标准的ESM模块化

报错二：identifier(Array) is disallowed in sjs

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-1VHbjht4-1669342568063)(https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/1e87f23fa3c64da9b597146947c09c12~tplv-k3u1fbpfcp-zoom-1.image)]

这段代码存在两个问题：

• 1. 在sjs语法中的数组数据类型为array
• 2. 其次sjs语法中数组上没有isArray()方法，这里要借助sjs支持的方法重写isArray的判断逻辑

报错三：本质上同报错二

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-thfDUUWc-1669342568063)(https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/e11ba1ca55504ca9882878a5726406e4~tplv-k3u1fbpfcp-zoom-1.image)]

本质上同报错二，sjs语法中的对象不支持keys()方法，必须绕开语法不支持的api实现功能，自测通过有两种重写方式：

// 直接重写封装keys()方法
function keys(obj) {
  return JSON.stringify(obj)
    .replace(REGEXP, '')
    .split(',')
    .map(function(item) {
      return item.split(':')[0];
    });
}

// keys()本质是遍历对象获取key的list，手写遍历对象
const str = JSON.stringify(conf);
const arr = str.slice(1, str.length-1).split(',');
for (let i=0; i<arr.length; i++) {
  const item = arr[i].split(':');
  const key = item[0] && item[0].slice(1, item[0].length-1);
  conf[key] && mods.push(key);
}

基本上所有关于sjs语法或者数据类型的报错，都可以参考这份sjs语法文档进行解决https://opendocs.alipay.com/mini/framework/sjs

功能验证

实现曝光埋点通常都会考虑借助IntersectionObserver对象，支付宝小程序也有自己的API支持。阅读IntersectionObserver对象相关参考文档实现曝光埋点上报后就可以基于2.7+基础库进行验证了。

本地上报成功！

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-xJFiJ8Kp-1669342568063)(https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/54a8cee553aa493c8f99b7e9ffb8ff4b~tplv-k3u1fbpfcp-zoom-1.image)]

代码编译打包升级基础库版本

准备上线的时候发现生产环境下埋点上报不成功：

• 借助开发这边工具构建上传上报成功
• 借助jenkins构建打包上传无法上报

于是怀疑是build-upload中间出了问题，所以考虑是项目根目录 mini.project.json 中有关项目编译、打包策略的配置有问题，使用uniapp框架的小程序对应配置文件为manifest.json。

阅读文档之后发现需要开启enableAppxNg为true，所以前面推荐改代码方式启动开发者工具以基础库2.x版本编译，既不用重复勾选，而且生产环境下打包也要手动开启，避免这里走弯路了。

"mp-alipay": {
  "enableAppxNg": true
}

• 项目配置 — https://opendocs.alipay.com/mini/framework/project
• uniapp manifest.json — https://uniapp.dcloud.net.cn/collocation/manifest.html#mp-alipay

同时还有使用小程序cli构建打包和通过nodejs API minidev.build() 传参获取编译打包结果等方式可以参考 — https://opendocs.alipay.com/mini/02q17m

最后

头一次开发支付宝小程序就要搞升级 QAQ，虽然也查了不少文档逛了不少社区问答，但可能还有诸多理解不到位的地方，欢迎指正，也记录一下给新手避我踩过的坑吧～

总归遇到问题时还是要多读文档，其次官方社区看看别人的提问和解决方案。

参考资料

• 基础库 — https://opendocs.alipay.com/mini/framework/lib
• 本地IDE升级基础库版本2.x — https://opendocs.alipay.com/mini/framework/lib-upgrade-v2
• sjs语法 — https://opendocs.alipay.com/mini/framework/sjs
• 节点查询创建IntersectionObserver 对象实例 — https://opendocs.alipay.com/mini/api/intersectionobserver
• IntersectionObserver 对象实例 — https://opendocs.alipay.com/mini/api/pra7yc
• 项目配置 — https://opendocs.alipay.com/mini/framework/project
• uniapp manifest.json — https://uniapp.dcloud.net.cn/collocation/manifest.html#mp-alipay