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 來開啟壓縮，例如編譯微信小程序

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

# Windows
$ 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 有你更精彩！