Taro 版本升级权威指南

Taro 是一款由京东凹凸实验室推出的开放式跨端跨框架解决方案，致力于解决小程序、H5、React Native 的跨端同构问题，支持同时使用 React 和 Vue 来进行开发。本文由 Taro 团队成员隔壁老李撰写，旨在帮助 Taro 开发者厘清当前 Taro 多版本之间关系的那些事儿，同时解答有关 Taro 3、Taro RN 支持以及 Taro UI 的一些困惑。

自从 Taro 在今年 7 月份推出 3.0 版本，宣布同时支持 React 和 Vue 来开发跨端应用之后，Taro 的关注度得到了进一步地提升，很多开发者开始尝试升级自身项目到 3.0 来体验新的特性，同时，Taro 社区也开始迎来一些新朋友，业界有很多 Vue 开发者在做技术选型时开始将目光投向 Taro。

但由于 Taro 大版本之间差异较大，而社区内很多关于 Taro 的教程文章以及示例项目目前还停留 Taro 1/2 时代，导致很多开发者使用 Taro 3.0 尝试时出现奇怪的问题，所以 Taro 团队想通过本文帮助大家理解 Taro 各个版本之间的联系，协助大家更好地完成版本迁移，避免出现一些难以解决的奇怪问题。

区分 Taro 版本的火眼金睛

Taro 目前有 3 个大版本，但如果按照架构来真正划分时代的话，Taro 1/2 属于第一代架构，而 Taro 3 则属于第二代架构，两代架构差异巨大，甚至可以完全认为是 2 个框架。当然，这只是对于框架内核而言，对于开发者，Taro 团队已经尽量在保证大版本之间的兼容性，着力降低版本迁移的难度。

Taro 1/2

Taro 1/2 属于编译型架构，主要通过对类 React 代码进行语法编译转换地方式，得到各个端可以运行的代码，再配合非常轻量的运行时适配，以及根据标准组件库、API 进行差异抹平，从而实现多端适配的目的，整体架构如下。

而 Taro 1 与 Taro 2 的都是基于这种架构建立的方案，他们之间的区别主要是 Taro 1 在小程序端是自建构建体系，而 Taro 2 则是所有端都采用 Webpack 进行编译，可以降低 Taro 自身编译系统的复杂度，同时能够让开发者使用 Webpack 的生态来自定义编译过程和结果，可以认为 Taro 2 是 Taro 1 和 3 之间的一个过渡性版本。

Taro 3

Taro 3 则可以大致理解为解释型架构（相对于 Taro 1/2 而言），主要通过在小程序端模拟实现 DOM、BOM API 来让前端框架直接运行在小程序环境中，从而达到小程序和 H5 统一的目的，而对于生命周期、组件库、API、路由等差异，我们依然可以通过定义统一标准，各端负责各自实现的方式来进行抹平。而正因为 Taro 3 的原理，所以我们可以在 Taro 3 中同时支持 React、Vue 等框架，甚至我们还支持了 jQuery，在不久的将来我们还能支持让开发自定义地去拓展其他框架的支持，比如 Angular，Taro 3 整体架构如下。

版本选择的取舍

通过上述内容可以看出，Taro 两代架构之间差异巨大，从而也就导致了他们之间的特性也很不一样。Taro 1/2 和 Taro 3 之间特性的差异主要体现在开发体验与性能上。

从开发体验上看，Taro 3 明显是优于 Taro 1/2 的，受益于 Taro 3 架构的原理，我们可以在 Taro 3 中使用完整的 React、Vue 语法特性来进行开发，从而在开发体验上让多端开发无限接近于 Web 开发，这对深耕 Web 而初次接触小程序的开发者来说是非常友好的。而对 Taro 熟悉的朋友肯定知道 Taro 1/2 在开发时会有诸多限制，尤其是在 JSX 书写上，我们总会需要一些手段来绕过这些限制，这就导致开发体验小有不足。

从性能上看，某些情况下 Taro 1/2 会优于 Taro 3，如果你的应用非常复杂，页面节点非常多，有非常多的大规模更新操作，对性能要求比较苛刻的话，Taro 1/2 会是不错的选择，而 Taro 1 和 2 我们更推荐使用 Taro 2。当然，根据我们的测试，对于大部分应用来说 Taro 1/2 和 Taro 3 的性能差异并不明显，我们后续会给出 benchmark 来印证这一点，而且，对于 Taro 3 本身在性能存在劣势的场景，Taro 官方团队已经给出了相应的解决方案来应对。比如，提升首次渲染速度，我们可以使用预渲染；对于无限滚动加载的列表场景，我们提供了虚拟列表组件。

对于开发者来说，开发体验和性能往往是需要权衡来寻找平衡点的，缺一不可，所以现阶段，我们更加推荐使用 Taro 3 来开发多端应用。而且现阶段 Taro 团队的研发重心主要放在 Taro 3 上，新的特性会优先在 Taro 3 上进行尝试，所以，在未来 Taro 3 将更具有想象力，会有更多好玩的东西推出来。

平滑升级不完全指南

Taro 2 和 Taro 3 都有对应的迁移指南，根据迁移指南往往能规避大部分的问题。

Taro 1 升级到 Taro 2 的迁移指南。

Taro 1/2 升级到 Taro 3 的迁移指南。

当然，迁移指南肯定无法覆盖到所有问题所有情况，我们在 Taro 交流群的日常交流中总是能观察到一些迁移的问题，所以在这里，我们将梳理一遍迁移指南，同时就一些常见的问题，再做一些说明补充，来解答开发者们的升级困惑。

Taro 1 升级到 Taro 2

Taro 1 升 Taro 2 所需要做的工作并不多，根据迁移指南，主要是新增了一个 @tarojs/mini-runner 依赖，以及对编译配置的调整，而在这里容易出问题的往往是在编译配置调整中，所以我们总结了一下针对编译配置的调整内容。

• plugins 配置调整，调整前是一个对象，调整后为一个数组，用来配置 Taro 插件，非常值得注意的是这个配置请与 babel 配置里的 plugins 区分开来，后者是用来配置 babel 插件的，这是一个非常常见的配置错误
• babel、csso、uglify 等配置从旧的 plugins 配置中移出来了，调整为与 sourceRoot 和 outputRoot 等同级的配置项
• weapp 配置项改名为 mini
• postcss 配置项下去掉 module 这一级配置，原 module 下的配置项直接置于 postcss 下

关于 async functions 的使用

同时，从 Taro 2 开始，使用 async functions 不再需要安装 @tarojs/async-await 依赖了，而是通过安装 babel 插件 babel-plugin-transform-runtime 配合 babel-runtime 来实现支持，具体请查看文档异步编程指南。

而在 Taro 3 中则不再需要手动安装配置，Taro 的官方 babel 预设 babel-preset-taro 已经内置了相关配置。

Taro 1/2 升级到 Taro 3

Taro 1/2 升级到 Taro 3 则相对来说要麻烦许多，但是迁移指南中其实介绍得已经非常详细了，我们在这里总结一下需要调整的内容。

文件调整

文件调整主要如下：

• babel 配置，在项目目录下新增了 babel.config.js 配置文件来配置 babel，为此，请去掉编译配置（config/index.js）中的 babel 配置，请参见说明
• 项目/页面配置，新增项目/页面同名的配置文件 *.config.js（或者 *.config.ts）, * 代表页面/项目文件的文件名，config 文件必须和页面/项目文件在同一文件夹，请参见说明

编译配置调整

主要参考上述 Taro 1 升级到 Taro 2 时的调整，新增 Taro 3 特有配置 framework 配置，取值为使用的框架（react, nerv, vue, vue3），请参见说明

项目依赖调整

在 Taro 3 中有很多旧的项目依赖已经不再需要了，例如之前做平台运行时兼容的 @tarojs/taro-weapp、@tarojs/taro-alipay 等等，而同时也新增了一些新依赖项，例如 @tarojs/runtime 等，具体 Taro 3 会需要哪些依赖，可以通过创建 Taro 示例项目看到，在这里我们列出了 Taro 3 目前仍需使用的 NPM 包名及其具体作用。

NPM 包	描述
babel-preset-taro	给 Taro 项目使用的 babel preset
@tarojs/taro	暴露给应用开发者的 Taro 核心 API
@tarojs/shared	Taro 内部使用的 utils
@tarojs/api	暴露给 @tarojs/taro 的所有端的公有 API
@tarojs/taro-h5	暴露给 @tarojs/taro 的 H5 端 API
@tarojs/router	Taro H5 路由
@tarojs/react	基于 react-reconciler 的小程序专用 React 渲染器
@tarojs/cli	Taro 开发工具
@tarojs/extend	Taro 扩展，包含 jQuery API 等
@tarojs/helper	内部给 CLI 和 runner 使用辅助方法集
@tarojs/service	Taro 插件化内核
@tarojs/taro-loader	露给 @tarojs/mini-runner 和 @tarojs/webpack-runner 使用的 Webpack loader
@tarojs/runner-utils	暴露给 @tarojs/mini-runner 和 @tarojs/webpack-runner 的公用工具函数
@tarojs/webpack-runner	Taro H5 端 Webpack 打包编译工具
@tarojs/mini-runner	Taro 小程序 端 Webpack 打包编译工具
@tarojs/components	Taro 标准组件库，H5 版
@tarojs/taroize	Taro 小程序反向编译器
@tarojs/with-weapp	反向转换的运行时适配器
eslint-config-taro	Taro ESLint 规则
eslint-plugin-taro	Taro ESLint 插件

代码调整

代码调整主要如下：

• API 引入，前端框架（React/Nerv/Vue）自身的 API 直接从框架引入，与 Web 保持一致，只有 Taro 提供的相关 API，还是从 @tarojs/taro 引入，请参见说明
• App 代码调整，对于 React/Nerv 项目，项目入口 App 的 render 函数固定修改为返回 this.props.children，如下

import { Component } from 'react'
import './app.scss'

class App extends Component {
  render() {
    return this.props.children
  }
}
export default App

• 路由功能，使用 getCurrentInstance().router 替代 this.$router，getCurrentInstance 作为新 API 从 @tarojs/taro 引入，请参见说明
• 生命周期，主要是使用 React 后，带来的生命周期调整，请参见说明
• 使用第三方 React 库，对于 redux、mobx 等 React 生态库，可以直接像 Web 开发那样直接使用，请参见说明
• Ref & DOM，请参见说明
• 不再需要传入 $scope，在 Taro 1/2 时调用某些 API 需要传入 this.$scope，相当于传入组件对应的小程序原生对象，而 Taro 3 则不再需要，具体请参见说明
• 样式调整，组件直接受全局样式影响，不再需要设置 addGlobalClasses，请参见说明

当然，迁移指南内容并不仅仅局限于版本迁移，由于 Taro 3 相对与 Taro 1/2 有很多 breaking changes，所以建议使用 Taro 3 的开发者都能在开发前阅读一遍迁移指南。

不得不唠叨一下 Taro 3 的正确使用姿势

正如前文所提到的，目前有很多开发者是从 Taro 3 才开始接触 Taro，而目前市面上很多 Taro 相关的教程和项目都是 Taro 1/2 的，这对于很多开发者来说会造成不小的困惑，所以行文到此，我们希望列举一些常见问题来帮助开发者规避掉一些不必要的错误。

Taro 多版本共存问题

很多开发曾经使用 Taro 旧版本开发过项目，已经在全局安装了 Taro，但是想同时体验到 Taro 3，应该如何进行操作？

我们提供了两种思路：

• 如果是需要新创建 Taro 3 项目，可以使用 nvm 来管理 node 版本，通过安装不同 node 版本来安装不同版本的 Taro CLI，从而解决 Taro 多版本共存的问题
• 如果是部分已有项目需要升级到 Taro 3，可以在这些项目本地安装相应版本的 Taro CLI，这样通过 yarn 或者 npm 执行命令的话就会直接使用本地安装的 Taro CLI，安装方式 yarn add @tarojs/cli

将 Taro CLI 版本与项目中 Taro 相关依赖的版本保持一致

请时刻注意将 Taro CLI 版本与项目中 Taro 相关依赖的版本保持一致。

CLI 与项目依赖版本不一致是导致很多问题出现的源头之一。例如，Taro CLI 版本为 3.0.8，那么 Taro 相关依赖的版本也必须是 3.0.8，Taro 相关包名可以从这个列表得知，具体依赖项版本可以使用 taro info 命令或者通过 package.json 就能知晓。

如果发现不一致的情况可以使用 Taro 升级命令 taro update self [版本号] 和 taro update project [版本号]来分别将 CLI 和项目依赖升级到指定版本；或者也可以手动安装相应版本 CLI，修改 package.json 依赖版本号，然后重装依赖来解决。

使用路由

在 Taro 3 中使用路由在前文的版本迁移部分已有提及，同时需要了解更多内容可以前往官方文档查看。

非常值得注意的是，无论是获取项目传入参数还是页面入参，都是通过 getCurrentInstance().router 来获取的，具体使用如下。

import { getCurrentInstance } from '@tarojs/taro'
import React, { Component } from 'react'

export default class C extends Component {
  componentDidMount() {
    console.log(getCurrentInstance().router.params)
  }
}

如何获取页面节点信息

由于 Taro 3 设计机制的原因，需要在新增的 onReady 生命周期内才能调用 Taro API 正确获取页面节点信息，小程序和 H5 都是如此。

而同时，在微信小程序中当页面节点嵌套过深时，超过一定层级（默认 16 级，可以通过编译配置 baseLevel 来控制）时，Taro 将转而使用自定义组件，然后再开启新的循环，在这种情况要争取获取页面节点信息的话，需要使用 跨自定义组件的后代选择器 来进行选择，可以参见 Taro 相关 issue。

Taro UI 是不是不支持 Taro 3 了

在 Taro 3 中依然可以使用 Taro UI，目前需要安装 Taro UI 的 alpha 版本。

$ yarn add taro-ui@next

Taro UI 作为 Taro 的官方 UI 库，依然处于维护状态，目前主要依靠社区力量在进行维护，同时也非常欢迎更多社区开发人员共同参与到 Taro UI 的迭代中来。

Taro UI 有没有 Vue 版本

目前，Taro 官方没有推出 Vue 版本的 Taro UI 库，但在社区中有 Vue 版本的解决方案，如果使用 Vue 进行开发可以尝试 taro-ui-vue。

为什么 Taro 3 打包出来的应用体积巨大

很多朋友会发现 Taro 3 的项目在预览的时候打包出来的包大小相比 Taro 1/2 要大上很多，然后非常紧张用了 Taro 3 会不会导致自己的主包超限。

诚然，在预览的时候 Taro 3 默认生成的包会比较大，主要是因为为了方便调试，预览时引用的 React 和 Vue 用的是调试用库，而且同时预览时会生成 sourceMap，这就导致预览时生成的包会大很多，但是在打包生产包（去掉 --watch）时，最终生成包还是会很小的，对线上不会有太大影响，同时 Taro 团队也正在尝试不断优化生产包大小，进一步优化 Taro 性能。

如果想要在预览时降低包大小，可以设置 NODE_ENV 为 production 来开启压缩，例如编译微信小程序

# Bash
$ NODE_ENV=production taro build --type weapp --watch

# CMD
$ set NODE_ENV=production && taro build --type weapp --watch

在 Taro 3 中使用小程序原生页面及组件

在 Taro 3 中依然可以像 Taro 1/2 那样引入小程序原生页面及组件，且使用方式大体一致，不过在某些情况有些细微差别，比如 slot 的使用，在 Taro 1/2 中可以直接使用 slot 标签，而在 Taro 3 中则需要从 @tarojs/components 中引入 Slot 组件然后再进行使用。

import Taro from '@tarojs/taro'
import React, { Component } from 'react'
import { View, Text, Slot } from '@tarojs/components'

export default class Index extends Component {
  state = {
    show: false,
    date: '',
  }
  render() {
    const { show, date } = this.state
    return (
      <View className="index">
        <van-button type="primary" onClick={this.showCalendar}>
          显示日历
        </van-button>
        <van-calendar show={show} showConfirm type="range" onClose={this.closeCalendar} onConfirm={this.onConfirm}>
          <Slot name="title">
            <View>Hello world</View>
          </Slot>
        </van-calendar>
      </View>
    )
  }
}

具体使用情况可以参考项目 taro3-vant-sample。

有哪些 Taro 官方的示例项目

目前 Taro 3 的社区示例项目还在完善中，Taro 官方则分别针对 React 和 Vue 提供了示例的组件库项目以供参考，安装最新版本的 Taro CLI，在创建项目时选择社区优质模板源创建即可进行体验。

同时，Taro 官方还提供了一个 TodoMVC 项目以供参考学习，React 和 Vue 示例分别在 react 和 vue 分支上。

Taro 物料市场中哪些物料能在 Taro 3 中使用

目前 Taro 物料市场没有做好针对物料的版本区分，我们会尽快启动这一项工作，为每个物料打上版本标识，当下要识别哪些物料能在 Taro 3 中使用，只能通过物料本身的 Taro 依赖项来进行识别。

再聊聊 Taro 的近期动作

Taro 社区及官方团队目前主要在集中人力做以下几项工作

实现支持平台与框架的自定义扩展

细心的朋友应该已经发现，进入 Taro 3 时代，Taro 的推广 Slogan 已经由「多端统一开发解决方案」变成了「开放式跨端跨框架解决方案」，那么这两者之间有何差异呢？

可以看出「开放式跨端跨框架解决方案」包含了多端统一开发的特性，同时支持跨框架开发，而且更重要的是能够成为一个开放式的解决方案，我们希望开发者可以根据 Taro 提供的 API 开发一个插件就能实现自己去为 Taro 扩展更多平台与前端框架的支持，例如未来有些新的平台推出小程序，或者有人希望能在 Taro 中使用 Angular 等更多的前端框架，那么就可以通过 Taro 的开放式机制来自行扩展，而不用等待 Taro 官方来进行支持，Taro 将只作为一个跨端适配的平台，所有的可能性都可以让社区自己去自由发掘。

实现小程序与 Web 的同构

在当前 Taro 的设计下，使用 Taro 开发必须使用 Taro 标准组件库中的组件，而不能直接使用大家熟悉的 HTML 标签。我们正在努力打破这一藩篱，寻求支持让开发人员可以直接使用 HTML 标签来开发小程序的方案。

这样，既能进一步让 Taro 的开发体验接近 Web， 同时也能让一些 Web 生态资源可以直接运行在小程序中，极大降低从 Web 迁移到小程序的成本。

说说缺席的 Taro 3 RN 支持

很多朋友在升级到 Taro 3 之后都会发出疑问：RN 是不再支持了吗？

Taro 3 没有支持 RN 适配，让很多使用 Taro 开发 RN 应用的朋友措手不及，经常在群里能看到上述灵魂拷问。

事实上 Taro 并没有抛弃 RN，目前 Taro 3 RN 适配工作已经由 「58 同城」开发团队接管，进行适配支持，目前这项工作已经正在紧锣密鼓进行，相信不久的将来就能看到在 Taro 3 中 RN 的支持王者归来。而这一次的通力协作也意味着 Taro 核心团队正不断成长为一个跨公司的团队，在未来一定会有更多灵感的碰撞，为社区开发者带来更多精彩的功能。

总结一下

从目前的业界反馈与 Taro 自身规划来看，Taro 3 是一个非常值得尝试和期待的版本，已经有非常多的开发者开始使用 Taro 3 开发应用，在未来我们也会不断完善功能与文档，为大家带来更棒的开发体验。升级到 Taro 3 的过程或许稍显艰辛，但有任何问题，欢迎大家通过交流群和 GitHub issues 向我们进行反馈。

同时，诚挚邀请您与 Taro 官方团队交流您的使用情况，您的反馈是 Taro 前进的动力！请戳此完成 Taro 使用调研问卷，提交问卷，将有可能获得 Taro 团队的红包哦！！感谢一路相伴，Taro 有你更精彩！