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

朝生暮落
1,261 阅读6分钟

问题起因

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

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

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

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

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

什么是基础库

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

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

这里有一份官方解读～

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

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

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

首先官方给出的解释：

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

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

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

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

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

升级基础库

参照文档本地IDE升级 — opendocs.alipay.com/mini/framew…

文档提供了两种方式：

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

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

解决报错

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

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

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

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

这段代码存在两个问题：

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

报错三：本质上同报错二

本质上同报错二，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语法文档进行解决opendocs.alipay.com/mini/framew…

功能验证

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

本地上报成功！

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

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

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

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

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

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

或者直接开启formate2，也会默认开启 "enableAppxNg": true

"mp-alipay": {
   "format": 2,
   "compileType": "mini"
}

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

最后

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

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

参考资料

avatar
文章
阅读
粉丝