本文是将 Taro 版本从 v3.5.6 升级到 v3.6.22 的项目实战，基于 Vue 2 的框架，采用 webpack5 编译器，node 版本 v16.14.0。
前言
Taro 是一个跨端跨框架的开放式解决方案，支持使用 Vue/Vue3/React 框架进行小程序等应用开发。
目前我们团队已经基于 Taro v3.5.6 的版本开发了数十个跨端项目，并将其成功应用于生产环境。然而，时至今日，Taro 开源社区在 v3.5.6 版本之后又推出了近 30 个迭代版本，其中包括一次重大的框架升级。在这一过程中，引入了众多新特性，例如路由库支持、网络请求库支持和鸿蒙插件支持，同时也解决了许多长期存在的问题。鉴于此，我们决定对已有项目中的 Taro 版本进行一致性升级。
为了确保项目在 Taro 版本升级后依然保持稳定性，我们经过了长时间的测试和验证，并通过提交 PR 的方式解决了多项特性问题。截至目前，Taro v3.6.22 版本表现出色，稳定可靠。
本次升级指南将聚焦于 Taro 版本从 v3.5.6 升级到 v3.6.22 的过程，详细介绍了开发者需要关注的业务代码调整和新增特性的注意事项。
升级优势
Taro 框架最新版本的升级为跨端开发领域带来了一系列引人注目的优势，强化了其在实现统一开发体验方面的实力：
首先，全新跨端能力的支持为开发者提供了更为一致的开发体验。新增的路由库和网络请求库使得在不同平台进行页面导航和网络请求处理更加便捷，从而降低了开发复杂度，提升了开发效率。
其次，跨框架组件库的增强显著提升了组件的兼容性。通过 Web 端适配器的升级，开发者可以更好地处理组件在不同平台上的展示，而独立管理虚拟列表则进一步优化了性能，使得应用在各个平台上都能获得更流畅的体验。
在平台能力支持方面，Taro 框架的进化也十分引人注目。新增对鸿蒙端平台插件的支持，使得开发者能够轻松将应用拓展到鸿蒙平台，从而触达更多用户（鸿蒙端的全面支持将在 Taro 4.x 版本）。对 React Native 模块的重构为移动端开发提供了更稳定高效的基础，而 Web 端能力的增强使得在浏览器环境中开发应用变得更加强大灵活。
同时，在过去的版本中，开发者常常遇到的路由切换不准确和网络请求能力不足的问题，在最新版本中都得到了全面解决。
综合而言，Taro 框架此次升级为开发者带来了更为便利的开发工具和更强大的跨端能力，使得在不同平台上构建应用变得更加高效、稳定且一致。
平滑升级指南
当然，升级指南肯定无法覆盖到所有问题所有情况，在 Taro 交流群的日常交流中也总是能观察到一些迁移的问题，所以在这里，我们花大量时间对升级后的项目进行了功能验证，并梳理出了一份迁移指南，同时就一些常见的问题，再做一些说明补充，来解答开发者们的升级困惑。我们致力于最大程度减轻开发者的迁移负担，使升级过程更加平滑。
依赖调整
1、Vue2 项目
1、更新 @tarojs/xxx 依赖，从 3.5.6 升级为 3.6.22。
2、更新 @tarojs/plugin-inject 依赖，从 1.0.2 升级为 3.6.22。
3、更新 webpack 依赖，从 5.69.0 升级为 5.78.0。
4、更新 eslint-plugin-vue 依赖，从 ^6.x 升级为 ^8.x。
5、新增 @tarojs/plugin-platform-h5 、@tarojs/taro-loader 依赖，版本为 3.6.22。
6、新增 postcss 依赖，版本为 ^8.4.18。
7、移除@tarojs/router、@tarojs/taro-h5 依赖，不再需要额外声明。
2、Vue3 项目
1、更新 @tarojs/xxx 依赖，从 3.5.6 升级为 3.6.22。
2、更新 @tarojs/plugin-inject 依赖，从 1.0.2 升级为 3.6.22。
3、更新 webpack 依赖，从 5.69.0 升级为 5.78.0。
4、更新 eslint-plugin-vue 依赖，从 ^6.x 升级为 ^8.x。
5、更新 vue-loader 依赖 ,从 “^16.0.0-beta.8” 修改为 “^17.0.0”。
6、新增 @tarojs/plugin-platform-h5 、@tarojs/taro-loader 依赖，版本为 3.6.22。
7、新增 postcss 依赖，版本为 ^8.4.18。
8、移除@tarojs/router、@tarojs/taro-h5 依赖，不再需要额外声明。
代码调整
1、CSS 文件引入方式调整：
在 CSS 文件中，原先类似 import "iconfont" 不指定文件后缀的引入方式，需要调整为 import "iconfont.css"，携带样式文件后缀。
2、动态获取模块内容注意事项：
在编译时通过 require.context 方式动态获取模块内容时，目录下不能有 index 文件。否则，在获取目录路径时，会直接解析到对应的 index 文件，导致解析失败。
3、H5 端路由模块变更：
H5 端的路由模块逻辑有较大改动。navigateBack 接口对于 delta 参数有了新的规则判断。框架会管理页面栈数量，每次新开页会 push 到页面栈中，刷新则会清空历史页面栈，只保留当前页面栈。当调用 navigateBack 接口，且传入参数 delta 大于现有页面栈数时，只会返回到框架管理的最早页面栈。在 H5 应用链接跳转过程中，如果 reload 刷新了页面，再想通过 navigateBack 接口返回到前几个页面，这是办不到的。在这种情况下，建议直接使用浏览器提供的 js 方法 history.go(-delta) 来实现。如果想返回到 H5 应用的首页，建议直接使用 relaunch 接口方法。
4、H5 端 block 组件改造：
H5 端的 block 组件进行了改造，采用了 vue-fragment 组件技术移除了以前的空 div 标签。然而，当使用 v-for 遍历 block 组件时，存在一定的问题。因此，暂时建议项目中不要使用 block 组件，可以用 view 组件代替。
版本特性对照表
在 Taro 内核版本升级的决策过程中，我们始终将框架能力的稳定性放在首要位置。我们致力于避免出现白屏、全面样式丢失、常用组件不可用等可能阻塞业务流程的问题。其次，我们考虑新增特性的功能全面性等问题，确保升级不仅仅是技术提升，更能带来更为丰富的功能体验。
在整个升级期间，我们积极参与 Taro 的开源建设，通过提交 PR 的方式不断解决了一些重大问题。一些例子包括 H5 端组件样式丢失和功能不可用问题、自定义注入插件 plugin-inject 不可用问题、H5 端开启下拉刷新后白屏问题等。通过这些努力和磨合，我们最终找到了一个高可用的稳定版本。
以下是近期版本的特性表，展示了我们在升级后引入的新功能和优化，为用户提供更出色的使用体验。
| 版本号 | 更新说明 | 备注 |
|---|---|---|
| 3.5.7 | 【特性】 H5: 1、新增 getLaunchOptionsSync，getEnterOptionsSync 【修复】 小程序: 1、修复 App 没有触发首次 componentDidShow 系列生命周期的问题 2、修复自动为数字类型的 CSS 变量与部分属性自动添加 px 后缀的问题 H5: 1、修复 onLaunch 参数的数据结构与小程序的不一致的问题 2、修复 request API 与小程序的网络请求处理不一致的问题 3、修复当 postcss-pxtransform 计算为 0 时不支持在 calc 表达式使用的问题 | / |
| 3.5.8 | 【特性】 小程序： 1、修复开启 html 转译插件后，部分元素属性没有进行映射导致更新失败 H5: 1、downloadFile 方法新增 timeout 字段 【修复】 H5: 1、修复 Button 组件 disabled 参数失效问题 | / |
| 3.5.9 | 【特性】 小程序： 1、支持 onUnhandledRejection 生命周期 | / |
| 3.5.10 | 【修复】 CLI 1、修复配置文件读取报错的问题 | / |
| 3.5.11 | 【修复】 H5: 1、修复 Tabbar 首页找不到 CurrentPage.path 导致的白屏问题 | / |
| 3.5.12 | 【修复】 小程序： 1、修复宿主环境同时使用插件页面和插件组件时 currentPage.route 异常中断插件组件渲染 | / |
| 3.6.0 | 【特性】 一、跨端能力支持 1、支持路由库 2、支持网络请求库 二、跨框架组件库 1、Web 端适配器升级，提升组件兼容性 2、虚拟列表单独管理 三、平台能力支持 1. 支持鸿蒙端平台插件 2. React Native 模块重构 3. Web 端能力增强 | / |
| 3.6.1 | 【特性】 1、plugin-inject 插件迁移到主仓 【修复】 1、为 vue 适配器映射 tap & click 事件 2、修复 vue2 v-model 语法使用 | / |
| 3.6.2 | 【修复】 H5: 1、修复自定义 defineConstants 覆盖问题 | / |
| 3.6.3 | 【修复】 小程序： 1、修复 Vant 组件的事件触发问题 2、支持开发者劫持小程序原生 request API H5: 1、修复 Swiper 组件循环时最后一帧不触发 onChange 的问题 2、支持 Textarea 组件的 focus 属性 | / |
| 3.6.4 | 【修复】 H5: 1、修复 taro-loader h5.js 中 page 变量没有 get 方法的问题 | / |
| 3.6.5 | 【修复】 小程序: 1、修复部分场景小程序热更新问题 H5: 1、修复 ready 页面在部分场景下不触发问题 | / |
| 3.6.6 | 【修复】 小程序: 1、修复 history.state 的返回不符合 web 规范的问题 H5: 1、支持 Textarea 组件的 confirm 事件 | / |
| 3.6.7 | 【修复】 小程序: 1、完善 Taro React Reconciler 的事件处理，修复 Input、Textarea 组件在受控情况下，value 值无法正常显示的问题 2、修复 app 样式引用 common 样式的语法问题 H5: 1、修复从普通页面返回 tabbar 页面时动画会消失的问题 2、修改 Taro.request 传入 array 类型数据序列化问题 | / |
| 3.6.8 | 【特性】 小程序: 1、新增 API：saveVideoToPhotosAlbum、saveImageToPhotosAlbum 、addPhoneRepeatCalendar、addPhoneCalendar、chooseMedia、getVideoInfo、canIUse 【修复】 小程序： 1、修复 Vue2 中使用 JSX 报错找不到 template 的问题 2、修复 Vue3 ref 引用的元素不能正确触发更新的问题 H5: 1、修复 Taro.showModal 当浏览器退回到上一页面时不消失的问题和遮罩层滚动穿透的问题 2、修复使用 ref 调用 Input、Textarea 组件的 focus 方法失败的问题 | H5 端组件不可用 |
| 3.6.9 | 【修复】 小程序： 1、优化获取节点的逻辑，增加其成功率 | / |
| 3.6.10 | 【修复】 小程序： 1、修复小程序模板在调用 xs.a 函数时参数漏传的问题 | / |
| 3.6.11 | 【特性】 1、支持虚拟瀑布流组件 2、虚拟列表能力优化 | / |
| 3.6.12 | 【修复】 1、修复输入框事件传入的函数不会更新 | / |
| 3.6.13 | 【特性】 1、优化 npm 包路径的获取，遵循原生小程序的规则 | H5 端构建失败，H5 端组件不可用 |
| 3.6.14 | 【修复】 小程序： 1、修复 Vue2/3 框架使用 h() 导致的报错问题 2、修复小程序模板在最后一层是字符串时递归模板没有走 template 别名的问题 H5: 1、修复 Vue2 创建 WebComponent 标签组件失效的问题 2、修复 webpack-runner 钩子不支持修改 componentConfig 的问题 3、修复 Vue3 没有办法在生产环境编译出 css 文件的问题 | 修复 H5 端组件不可用问题 |
| 3.6.15 | 【修复】 H5: 1、优化 React 组件适配器节点更新逻辑 | / |
| 3.6.16 | 【修复】 小程序: 1、修复 Webpack4 中 wxml loader 和 wxs loader 的路径问题 H5： 1、修复 @tarojs/plugin-inject 配置在 H5 端编译报错的问题 2、为 Taro.navigateBack API 添加数量上限限制 3、优化 Canvas 组件，自适应宽高配置、支持配置宽高 | 修复了 plugin-inject 插件的问题 |
| 3.6.17 | 【修复】 小程序: 1、修复 mini-runner 中 wxml、wxs loader 路径问题 2、修复 mini-runner 中 file-loader 和 webpack 在 windows 中使用路径失效问题 H5： 1、修复下拉刷新与 ScrollView 组件事件冲突、ScrollView 嵌套事件问题 2、修复 Swiper 组件渲染闪烁问题 3、优化路由页面显示控制，避免多页同现出现 | H5 端 enablePullDownRefresh 启用后白屏 |
| 3.6.18 | 【修复】 小程序: 1、修复文本节点列表更新时提示没有 key 的问题 2、修复 comp 和 custom-wrapper 没有重新引用 wxs 文件导致的 wxs 函数失效的问题 H5： 1、修复 max-height 错误配置导致的普通页面高度限制问题 2、修复当 app.config.js 设置 animation:false，路由跳转时上一个页面元素节点没有被隐藏 | / |
| 3.6.19 | 【修复】 小程序: 1、修复 Vue2 使用 componentsMap 配置时报错的问题 2、修复编译小程序时重复编译 App 和 Page 的问题 H5： 1、修复 react 适配组件库，样式抖动的问题 cli-convertor： 1、convertor 转换能力增强 | / |
| 3.6.20 | 【特性】 小程序: 1、升级 swc 与 esbuild：修复自定义 swc 插件的一系列问题、支持配置文件中使用 alias 和 define | / |
| 3.6.21 | 【修复】 小程序: 1、修复了小程序 Input 组件在使用 async onInput 回调时导致输入框闪烁的问题 2、修复了小程序中文本重叠的问题 3、修复了当嵌套层级过深时，模板变量 c 超过 baselevel 但没有进入新的嵌套循环的问题 | / |
| 3.6.22 | 【特性】 1、新增了 webpack 不同级别编译错误的处理方式 【修复】 1、修复了 esbuild-loader 的 AST 兼容问题 小程序： 1、修复了 alias 在递归组件配置中获取不完整的问题 H5： 1、修复了在 H5 端开启 enablePullDownRefresh 后导致页面白屏的问题 2、优化了 Image 组件兼容 mode 为空串和 src 无值的情况 | 修复了在 H5 端开启 enablePullDownRefresh 后导致页面白屏的问题 |
最后
在本次 Taro 版本升级实践中，尽管我们面临了一些挑战，但这也为我们带来了许多宝贵的经验。我们深刻认识到，框架升级不仅需要关注是否解决了技术上的遗留问题，还需要审慎考虑升级可能带来的潜在风险。
跨版本升级涉及大量的代码逻辑修改，开发人员难以完全掌握升级对项目的影响。因此，我们特别强调了安排足够的测试资源，以确保在升级后的系统中进行准确的全量回归测试。这是为了最大程度地降低潜在的问题，保证应用在新版本中的稳定性和可靠性。
除了关注问题的解决，我们还非常重视对新版本功能的充分了解和利用。框架升级不仅是问题修复的机会，更是引入创新和提升开发体验的良机。因此，我们鼓励团队深入研究新版本的特性，以充分发挥框架升级的潜力，提升应用的性能和功能。
总的来说，本次升级实践让我们更加明确了在框架升级过程中的关键因素，包括风险管理、全量测试和深入了解新特性。这些经验将指导我们未来更加智慧地进行框架升级，确保我们的应用始终运行在最佳状态。