支付宝小程序基础库升级2.x实践

问题起因

起因是内部的小程序埋点工具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

"mp-alipay": {
  "enableAppxNg": true
}
1
2
3