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


highlight: an-old-hope
theme: smartblue

问题起因

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

这是因为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语法文档进行解决https://opendocs.alipay.com/mini/framework/sjs

功能验证

实现曝光埋点通常都会考虑借助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": "miniprogram"
}

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

最后

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

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

参考资料

© 版权声明
THE END
喜欢就支持一下吧
点赞10 分享
评论 抢沙发
头像
欢迎您留下宝贵的见解!
提交
头像

昵称

取消
昵称表情代码图片

    暂无评论内容