Taro 3.x 跨版本升级小记

本文主要是记录将团队项目中的 Taro 版本从 3.4.3 跨版本升级到 3.6.8 过程中遇到的问题和解决方案，希望能在大家升级 Taro 过程中遇到问题时提供些解决问题的思路

一、背景

团队项目采用的 Taro 3.4.3 版本进行实际开发，使用 React 框架，兼容微信小程序和 H5 端。

默认情况下 Taro 有 2 个模式：

• development 模式用于开发时 taro build --type weapp --watch
• production 模式用于生产时 taro build --type weapp

在微信小程序开发过程中，期望能新增一个测试时的使用场景，并支持将构建产物上传到微信公众平台选为体验版。

模式	使用场景	环境变量
development	用于开发时	dev	1. 请求测试环境接口 2. 默认不压缩，包体积较大，无法上传到微信公众平台
production	用于生产时	prod	1. 请求生产环境接口 2. 开启压缩，包体积小
production	用于测试时	test	1. 请求测试环境接口 2. 开启压缩，包体积小

遇到些问题：

项目使用的测试环境代理联调工具在低版本 Taro 的 production 模式中构建会报错。

也有些需求：

对小程序包体积以及构建速度一直有优化的需求，而 Taro 框架在升级过程中，对体验和性能进行了优化和升级，并提供了一些性能优化的 API。

为此考虑升级 Taro 版本。

二、准备工作

查阅 Taro 官方相关的升级文档

1. Taro 更新日志 每次升级的内容都有比较清楚的描述
2. Taro 升级指南 针对大版本的升级可以查看相关的指南

Taro 3.5.x 的主要特性

1. 编译提速 基于 webpack5 构建了新的编译系统
2. 提供了 pnpm 包管理工具使用选项
3. 适配 React 18
4. H5 支持服务端渲染
5. H5 支持多页应用模式
6. 更多内容...

Taro 3.6.x 的主要特性

1. 支持路由库

2. 支持网络请求库

3. 更多内容...

本次升级选择了最新的版本 3.6.8 ，主要有以下几点考虑：

1. webpack5 编译速度提升
2. 适配 React18
3. 小程序内部实现优化，可减少约 200+KB 包体积，其中主包体积能减少约 140KB，同时降低内存占用
4. 直接通过 mode 的参数快速设置多个环境变量 👉 相关文档
5. 在最新版本种修复了一些已知问题

三、正式升级

升级指南

针对大版本的升级，Taro 有比较详细的指南，建议参考所要升级目标版本的升级指南完成升级。

团队项目升级的核心步骤如下：

1. node 版本升级，需要使用 node 16+ 的版本，低版本构建 H5 端的包时会报错

2. 升级 Taro CLI 👉 相关文档

有以下两种升级方式：

1. 通过安装指定版本的完成升级

   npm i @tarojs/[email protected] -g

2. 通过 cli 本身的命令升级

   taro update self 3.6.8 

3. 更新项目依赖

taro update project 3.6.8

如果依赖安装失败或安装成功后报错，可以尝试删除 node_modules、yarn.lock、package-lock.json、pnpm-lock.yaml 后重新安装依赖

4. React 项目需要额外安装 @pmmmwh/react-refresh-webpack-plugin 和 react-refresh

npm i @pmmmwh/react-refresh-webpack-plugin react-refresh --save-dev

5. 使用 webpack5

先卸载 @tarojs/mini-runner 和 @tarojs/webpack-runner

npm uninstall @tarojs/mini-runner @tarojs/webpack-runner

然后安装 @tarojs/webpack5-runner

npm install @tarojs/webpack5-runner

最后修改 Taro 编译配置

/** config/index.js */
const config = {
  compiler: 'webpack5',
}

升级中遇到的问题及解决方案

1. 使用 webpack5 构建内存溢出 JavaScript heap out of memory

问题描述

<--- Last few GCs --->

[482203:0x563619071c30]   190078 ms: Mark-sweep 1976.4 (2084.9) -> 1956.6 (2078.5) MB, 401.5 / 0.0 ms  (average mu = 0.260, current mu = 0.108) task scavenge might not succeed
[482203:0x563619071c30]   190677 ms: Mark-sweep 1974.9 (2080.7) -> 1958.6 (2080.7) MB, 395.6 / 0.0 ms  (average mu = 0.301, current mu = 0.340) allocation failure scavenge might not succeed

<--- JS stacktrace --->

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
 1: 0x5636168852a4 node::Abort() [webpack]
...

解决方案

问题应该是通过 alias 配置的 / 导致的循环引用的问题，去掉就好了

/** config/index.js */
{
    resolve: {
        alias: {
            // ...
            '/': path.resolve(__dirname, '..', 'src') // 去掉这行就好了
        }
    }
}

参考链接

• # Webpack v4 migration to v5 effort is running into a "JavaScript heap out of memory"

2. WXSS 文件编译错误

问题描述

unexpected "\" at post

解决方案

使用配置 compiler: 'webpack5' 后解决， @tarojs/mini-runner css-loader版本导致的异常

参考链接

• # 生成样式报错

3. 升级后h5 页面字体样式变大

问题描述

h5 字体偏大导致布局异常

解决方案

设置 deviceRatio

// config/index.js
deviceRatio: {
640: 2.34 / 2,
750: process.env.TARO_ENV === 'h5' ? 640 / 750 : 1, // 主要是这里
828: 1.81 / 2
},

参考链接

• 字体相比较3.4.x版本字体偏大 #12361

5. background 属性简写包含 background-size 时背景图片无法正常显示

问题描述

// background 属性简写
background: url('./url.png') center 100% / 100% no-repeat;

解决方案

该问题主要是 webpack5 中 css 解析器没有支持 background-size 属性的简写，需要修改代码的书写方式

// 修改代码
background: url('./url.png') center center no-repeat;
background-size: 100%;

参考链接

• Error: CSS: background: / is an incorrect operator
• CSS backgroundSize property lost when re-rendering an image URL inside of an adjacent background property #5030
• Do not use the CSS background shorthand property in React

6. Input 组件设置的 value 值为 undefined 时在 H5 中可能重复渲染导致内存溢出

问题描述

给 Input 组件设置的 value 值为 undefined 时， 在 H5 有可能会导致重复渲染

<Input value={value} />

解决方案

// 当 value 为 undefined 时，设置默认值
<Input value={vallue || ''} />

参考链接

• H5 Input组件如果绑定了Value，第二次更新组件，会触发死循环 #13734
• H5 Input组件问题

7.webpack5 开启持久化缓存后导致原生小程序组件（t-captcha ）接收不到 props

问题描述

// 开启 webpack5 的持久化缓存
cache: {
enable: true, // Webpack 持久化缓存配置，建议开启。默认配置请参考：https://docs.taro.zone/docs/config-detail#cache
},

开启之后，小程序原生的图形验证码插件无法传递 appId 等 props ，导致报告下载等相关功能无法正常使用

解决方案

Taro 的已知问题，先关闭持久化缓存，等版本更新后再观察

参考链接

• webpack5 开启持久化缓存小程序原生组件接收不到 props #13462

8. 插件依赖 "@tarojs/plugin-platform-h5" 加载失败，请检查插件配置

问题描述

UnhandledPromiseRejectionWarning: Error: 插件依赖 "@tarojs/plugin-platform-h5" 加载失败，请检查插件配置

解决方案

node 版本的问题，切换 node 版本为 16+ 即可

参考链接

• taro 3.0 官方模板运行报错 插件依赖 "@tarojs/plugin-platform-h5" 加载失败

四、升级前后对比

1. 通过 mode 参数构建多环境 👉 相关文档

当前项目中已新增了 test 模式，并且后续可快速配置其他需要的环境。

// 小程序（关闭 watch 模式）
npm run build:weapp      // 构建配置使用 production 模式，包体积小，请求正式环境接口，正式发布或提交到体验版
npm run build:weapp:test // 构建配置使用 production 模式，包体积小，请求正式环境接口，用于测试或提交到体验版

2. 包体积减少 200+KB，主包体积减少了 140+KB

3.使用webpack5，优化构建速度