一、Taro 简介

Taro 是一个开放式跨端跨框架开发解决方案，支持使用 React/Vue 等框架开发微信、支付宝、百度、字节跳动、QQ 小程序、H5、React Native 等应用。

核心优势：

• 一套代码，多端运行
• 支持 React/Vue 语法
• 拥有丰富的生态系统和插件
• 活跃的社区支持

本文重点介绍 Taro 与微信小程序之间的双向转换：原生微信小程序转 Taro 项目，以及 Taro 项目编译为微信小程序。

---

二、环境准备

2.1 Node 环境

Taro 项目基于 Node.js，要求 Node 版本 >= 16.20.0。推荐使用 nvm 管理 Node 版本：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装 Node.js
nvm install 18
nvm use 18

# 验证版本
node -v
npm -v

2.2 安装 Taro CLI

全局安装 @tarojs/cli：

# 使用 npm
npm install -g @tarojs/cli

# 使用 yarn
yarn global add @tarojs/cli

# 或使用 pnpm
pnpm add -g @tarojs/cli

查看 Taro 版本信息：

npm info @tarojs/cli

---

三、微信小程序转 Taro（反向转换）

Taro 可以把原生微信小程序应用转换为 Taro 项目，从而使项目成为多端应用。转换后的代码可读性高，能够继续使用 React 进行二次开发。

3.1 转换步骤

在微信小程序项目的根目录中运行：

# 转换命令
npx @tarojs/cli-convertor

转换后的代码保存在根目录下的 taroConvert 文件夹下。

3.2 安装依赖并运行

# 进入转换后的目录
cd taroConvert

# 安装依赖
npm install
# 或
yarn install
# 或
pnpm install

# 运行到微信小程序
npm run dev:weapp

3.3 编译到其他平台

Taro 支持编译到多个平台：

# 编译到 H5
npm run build:h5

# 编译到支付宝小程序
npm run build:alipay

# 编译到字节跳动小程序
npm run build:tt

# 编译到 QQ 小程序
npm run build:qq

---

四、Taro 项目编译为微信小程序（正向转换）

4.1 创建新项目

# 使用 CLI 创建项目
taro init myApp

# 或使用 npx
npx @tarojs/cli init myApp

按提示选择框架（React/Vue）、CSS 预处理器等配置。

4.2 编译命令

Taro 编译分为 dev 和 build 模式：

• dev 模式：增加 --watch 参数，监听文件修改
• build 模式：不监听文件修改，对代码进行压缩打包

# 开发模式（监听修改）
pnpm dev:weapp
# 或
yarn dev:weapp
# 或
npm run dev:weapp

# 生产模式（压缩打包）
pnpm build:weapp
# 或
yarn build:weapp
# 或
npm run build:weapp

# 使用 CLI 直接编译
taro build --type weapp --watch    # 开发模式
taro build --type weapp            # 生产模式

# npx 方式
npx taro build --type weapp --watch
npx taro build --type weapp

4.3 开启压缩预览

dev 模式生成的文件较大，可通过设置环境变量开启压缩：

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

# Bash / Linux / macOS
NODE_ENV=production taro build --type weapp --watch

---

五、微信开发者工具配置

5.1 下载并打开开发者工具

下载地址：微信开发者工具 (opens new window)

5.2 导入项目

选择 Taro 项目根目录下的 dist 目录（或配置中 outputRoot 设置的目录）进行预览。

5.3 ⚠️ 重要配置项

必须在开发者工具中关闭以下设置，否则可能报错：

设置项	操作
ES6 转 ES5	关闭
上传代码时样式自动补全	关闭
代码压缩上传	关闭

设置路径： 开发者工具 → 设置 → 项目设置

---

六、迁移差异说明

6.1 全局变量

原生小程序使用 getApp() 获取全局变量，Taro 推荐使用状态管理工具（Redux/Vuex），但也兼容原有写法：

React 方式：

// app.js
class App extends Component {
  taroGlobalData = {
    userInfo: null,
    token: ''
  }
}

// 页面中使用
function Index() {
  const app = Taro.getApp()
  console.log(app.userInfo)
}

Vue3 方式：

// app.js
import { createApp } from 'vue'
import { setGlobalDataPlugin } from '@tarojs/taro'

const App = createApp(...)
App.use(setGlobalDataPlugin, {
  userInfo: null,
  token: ''
})

6.2 API 的 scope

原生小程序中，自定义组件调用 createCanvasContext、createSelectorQuery 等 API 时需要传入 this。

在 Taro 中，一般不需要传入 scope，但在以下情况需要特殊处理：

1. 层级过深

当页面嵌套层级超过 16 层时，使用 <CustomWrapper> 组件包裹：

<CustomWrapper id='demo'>
  <Text>Hello world!</Text>
</CustomWrapper>

2. 获取 scope

// Taro v3.6.3+
onReady() {
  const ctx = document.getElementById('demo').ctx
}

// Taro v3.6.2 及以下
const page = Taro.getCurrentInstance().page
const scope = page.selectComponent('#demo')

6.3 WXS 支持

Taro v3.6.25+ 支持使用微信小程序的 wxs（仅支持 React 小程序端）：

// 使用 WXS
import { Wxs } from '@tarojs/components'

<Wxs module='utils'>
  {`
    module.exports = {
      format: function(price) {
        return '¥' + price
      }
    }
  `}
</Wxs>

---

七、常见问题

7.1 CLI 版本与依赖版本不一致

现象： 编译错误或运行时错误

解决： 保持 Taro CLI 版本与项目依赖版本一致：

# 升级 CLI
taro update self [版本号]

# 升级项目依赖
taro update project [版本号]

7.2 编译后体积过大

解决方案：

1. 使用 build 模式编译（自动压缩）
2. 配置分包加载
3. 使用 miniCssExtractPlugin 分离 CSS

7.3 样式不生效

排查：

1. 检查样式文件是否正确导入
2. 确认 CSS 选择器权重
3. 注意小程序样式隔离机制

7.4 API 调用失败

排查：

1. 检查 scope 是否正确传入
2. 确认 API 是否在 onReady 生命周期后调用
3. 查看 Taro 文档确认 API 支持情况

---

八、参考资料

• Taro 官方文档 (opens new window)
• 微信小程序转 Taro (opens new window)
• 从原生小程序迁移过来？ (opens new window)
• 编译配置详情 (opens new window)
• 小程序编译优化指南 (opens new window)
• 渐进式入门教程 (opens new window)

---

九、总结

Taro 提供了小程序双向转换能力，让开发者能够：

1. 存量项目升级：将原生微信小程序转换为 Taro 项目，实现跨端复用
2. 新项目多端开发：使用 React/Vue 开发一套代码，编译到多个小程序平台

核心流程：

原生微信小程序 → npx @tarojs/cli-convertor → Taro 项目
Taro 项目 → taro build --type weapp → 微信小程序

关键注意事项：

• 开发者工具必须关闭 ES6 转换、样式补全、代码压缩
• 保持 CLI 和依赖版本一致
• 注意全局变量、scope 等迁移差异

掌握 Taro 转换技巧，可以大幅提升小程序开发效率，实现一套代码多端运行。