Taro快速入门教程：环境安装与项目配置详解

Question

Taro 快速入门教程

Taro 是一个开放式跨端跨框架解决方案，支持使用 React、Vue 或 Nerv 等框架来开发微信、京东、百度、支付宝、字节跳动、QQ、飞书等小程序，以及 H5 和 React Native 应用。Taro 3 可以灵活转换到 H5、ReactNative 以及任意小程序平台，为开发者提供统一的开发体验。

环境安装

在开始之前，请确保 Node.js 版本不低于 16.20.0。建议使用 nvm 等工具管理 Node 版本。

安装 Taro CLI 工具：

npm install -g @tarojs/cli
# 或使用 yarn
yarn global add @tarojs/cli

如果遇到 sass 安装错误，可以尝试执行 npm install -g mirror-config-china 来配置镜像。要查看 Taro 的全部版本信息，可运行 npm info @tarojs/cli。

初始化项目

通过以下命令初始化一个新项目：

taro init taroApp

Taro 会自动安装项目依赖，并按照 yarn > cnpm > npm 的顺序检测包管理工具。

开发与编译

Taro 通过不同命令编译成各端代码，主要分为 dev 和 build 两种模式：

dev 模式：添加 --watch 参数以监听文件修改，适用于开发环境。此模式生成的文件较大，可通过设置环境变量 NODE_ENV 为 production 开启压缩，便于预览，但编译速度会下降。
build 模式：移除 --watch 参数，不监听文件修改并对代码进行压缩打包，适用于生产环境。

项目目录结构如下：

├── dist                      # 编译结果目录
├── config                    # 项目编译配置目录
│   ├── index.js              # 默认配置
│   ├── dev.js                # 开发环境配置
│   └── prod.js               # 生产环境配置
├── src                       # 源码目录
│   ├── pages                 # 页面文件目录
│   │   └── index             # index 页面目录
│   │       ├── index.js      # 页面逻辑
│   │       ├── index.css     # 页面样式
│   │       └── index.config.js # 页面配置
│   ├── app.js                # 项目入口文件
│   ├── app.css               # 项目总通用样式
│   └── app.config.js         # 项目入口配置
├── project.config.json       # 微信小程序项目配置
├── project.tt.json           # 抖音小程序项目配置
├── project.swan.json         # 百度小程序项目配置
├── project.qq.json           # QQ 小程序项目配置
├── babel.config.js           # Babel 配置
├── tsconfig.json             # TypeScript 配置
├── .eslintrc                 # ESLint 配置
└── package.json

编译配置

编译配置位于 config 目录，其中 index.js 为默认配置，dev.js 和 prod.js 分别对应开发和生产环境。Taro 支持使用 defineConfig 辅助函数进行配置，该函数可接受异步函数或基于命令和模式的情景配置，例如根据 mode 值返回不同配置。

小程序配置

全局配置文件 app.config.js 对应小程序的 app.json，遵循微信小程序规范，但作为 JS 文件支持逻辑编写。页面配置可通过 page.config.js 或使用 definePageConfig 宏函数定义，同样以微信小程序页面配置为规范。页面样式可通过 ES6 的 import 引入，路由需在 app.config.js 中配置。

模式与环境变量

Taro CLI 默认有 development 和 production 两种模式，其值取决于 NODE_ENV。你可以在项目根目录创建环境文件如 .env.development 和 .env.production，定义以 TARO_APP_ 开头的环境变量（例如 TARO_APP_API="https://api.tarojs.com"）。这些变量可在插件、配置文件和项目代码中使用，如 process.env.TARO_APP_API。

使用 --mode 参数可指定自定义模式加载对应环境变量，例如 taro build --type weapp --mode uat 会载入 .env.uat 文件。环境文件载入规则包括 .env（全局）、.env.local（本地忽略）、.env.[mode]（指定模式）和 .env.[mode].local（指定模式本地）。还可通过 --env-prefix 自定义环境变量前缀，但 TARO_APP_ID 始终会被加载。

设计稿与尺寸单位

Taro 中建议使用 px 或百分比作为尺寸单位。编译时 Taro 会自动转换样式尺寸，JS 中的行内样式可使用 Taro.pxTransform(10) API 进行运行时转换。配置中可通过 pxtransform 设置转换规则，如是否转换 1px、REM 单位精度、属性允许列表等。

全局与页面配置

app.config.js 用于全局配置，支持 defineAppConfig 宏函数以获取类型提示。通用配置项包括 pages（页面路径列表）、window（窗口表现）、tabBar（底部栏）和 subPackages（分包结构）。页面配置通过 .config.js 文件或 definePageConfig 宏函数定义，可覆盖全局配置的相同项。

项目配置

各小程序平台有专属项目配置文件，如微信小程序的 project.config.json、百度小程序的 project.swan.json 等，Taro 会相应适配。

Babel 配置

Babel 配置位于 babel.config.js，默认使用 babel-preset-taro preset。该 preset 根据项目技术栈选择 presets 和 plugins，支持 React、Vue 等框架。配置选项包括 useBuiltIns（polyfill 策略）、loose（宽松模式）、debug（调试模式）等，可根据需求调整以优化代码兼容性和体积。

通过以上步骤，你可以快速上手 Taro 开发，利用其跨端能力构建多平台应用。

Taro快速入门教程：环境安装与项目配置详解