Taro 升级总结和避坑指南

前言

公司内小程序技术栈使用 Taro + React + mobox，属于老项目且一直迭代，造成维护性差，性能差，急需进行一次技术改造，将现有问题进行改进。

首先第一点，需要升级 Taro 版本，因为 Taro 在升级过程中，也对体验和性能进行了优化和升级，并提供了一些性能优化的 API。

本文记一次 Taro 升级总结，本次升级 3.0.16 =》3.5.12，Taro 最新版本是 3.6.5，为什么不升级到最新版本，是因为新版本刚出来不久不太稳定，对项目稳定性来说是个考验。

准备工作

仔细查看 Taro 文档，每次升级内容文档内写的很清楚，但是不要看版本说明，这里仅写到了 3.4，具体每次升级内容需查看博客这里写的很清楚。注意请仔细阅读每次升级内容，确定自身升级到哪个版本。

对一些坑需要提前有些准备，例如：Node 升级影响，webpack 升级影响等。

本次升级我选择了 3.5.x 版本，主要有一下几点考虑：

1. 版本稳定性
2. webpack5 编译速度提升
3. 适配 React 18
4. 新增 App 生命周期
5. 小程序内部实现优化

对小程序的内部实现进行优化，减少约 50k 包体积，同时降低内存占用，减少 setData 发送的数据量。

正式升级

升级指南

参考所要升级版本的升级指南，例如我要升级的版本，文档给出的指南如下：

1. 升级 Taro CLI

升级全局的 Taro CLI：

npm i -g @tarojs/cli

或升级本地的 Taro CLI 工具：

npm i @tarojs/cli

1. 更新项目依赖

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

2.1 更新项目内的 Taro 相关依赖

把 package.json 中 Taro 相关依赖的版本修改为 3.5.0 后重新安装依赖。

2.2 使用 React 的项目

• 【Breaking】使用 React 的项目需要额外安装 @pmmmwh/react-refresh-webpack-plugin 和 react-refresh：

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

2.3 使用 PReact 的项目

• 【Breaking】使用 PReact 的项目需要额外安装 @prefresh/webpack 和 @prefresh/babel-plugin：

npm i @prefresh/webpack @prefresh/babel-plugin --save-dev

2.4 使用 Vue2 的项目

• 【Breaking】使用 Vue2 的项目需要额外安装 @vue/babel-preset-jsx：

npm i @vue/babel-preset-jsx --save-dev

2.5 使用 Vue3 的项目

• 【Breaking】使用 Vue3 的项目需要额外安装 @vue/babel-plugin-jsx：

npm i @vue/babel-plugin-jsx --save-dev

1. 使用 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. 使用 React 18

需要更新 react、react-dom、@types/react 的版本：

npm i react react-dom
npm i @types/react --save-dev

1. 使用 pnpm

因为 pnpm 不允许幽灵依赖的存在，因此开发者需要在项目中手动安装下列依赖：

dependencies 补充依赖：

"@tarojs/helper": "3.5.0",
"@tarojs/plugin-platform-weapp": "3.5.0",
"@tarojs/plugin-platform-alipay": "3.5.0",
"@tarojs/plugin-platform-tt": "3.5.0",
"@tarojs/plugin-platform-swan": "3.5.0",
"@tarojs/plugin-platform-jd": "3.5.0",
"@tarojs/plugin-platform-qq": "3.5.0",
"@tarojs/router": "3.5.0",
"@tarojs/shared": "3.5.0",
"@tarojs/taro-h5": "3.5.0",

devDependencies 补充依赖：

安装项目对应的 Webpack 版本，如 Webpack5：

"webpack": "^5.73.0"

升级问题及解决

先手动更改 package.json 的版本号到 3.5.0，删除掉 node_modules 和 package-lock.json, 然后重新安装依赖，启动项目

此问题是由于 node 版本过低导致

解决方法：升级 node 版本，我本次 node 版本升级到了 node v14.21.1 (npm v6.14.17)

此问题是由于 Taro 内部编译问题

解决方法：升级到 3.5.12 版本，已修复

此问题是由于 webpack 没有安装

解决方法：安装 webpack

此问题是由于 prebundle 多端文件打包报错 无法通过升级修复

解决方法：关闭 prebundle

config/index 文件下配置

compiler: {
    type: 'webpack5',
    prebundle: {
      enable: false,
      force: true,
    },
  },

此问题是由于 html-minifier 库在微信小程序上使用，压缩后的 input 标签没有闭合标签导致报错 无法通过升级修复

解决方法：mini.minifyXML.collapseWhitespace = false 或者通过 patch-package 修复 kangax/html-minifier#1065

此问题是 app.config.ts 丢失，swc 升级后编译有问题，app.config.ts 不生效或者全局配置缺少 pages 字段都可用此方法解决

解决方法：锁定 @swc/core 版本

 "resolutions": {
    "@swc/core": "1.3.42"
  }

切记 这种锁定版本只能用于 yarn 或者 pnmp 安装依赖才能生效

或者升级到 3.6.5 版本

总结

升级过后从编译和整体渲染上确实变快了很多，但是一些问题确实存在，希望此文章能给大家在升级 Taro 上能快速解决出现的问题。