Taro 开发快速入门手册
1. Taro 项目初始化
1.1. 安装Taro
1. 环境要求
在安装 Taro 之前，确保你的开发环境符合以下要求：
Node.js: 推荐使用 LTS 版本 (>= 14.0.0)。
npm: Taro 使用 npm 来管理依赖，通常 npm 会随 Node.js 一起安装。
2. 安装 Taro CLI
打开终端并运行以下命令来全局安装 Taro CLI：
npm install -g @tarojs/cli@4.0.7安装完成后，可以通过以下命令确认 Taro CLI 是否成功安装：
taro --version如果看到版本号，说明安装成功。
1.2. 项目搭建
1. 创建新项目
使用 Taro CLI 创建一个新的项目。可以通过以下命令来初始化项目：
taro init my-taro-app将 my-taro-app 替换为你希望的项目名称。运行命令后，系统会提示你选择项目模板。
2. 选择项目模板
Taro 提供了几种模板供选择：
默认模板: 适用于普通项目。
TypeScript 模板: 如果你希望使用 TypeScript 开发，请选择此项。
React Native 模板: 用于开发 React Native 应用。
根据需求选择合适的模板，然后系统将自动创建项目目录。
3. 安装依赖
进入项目目录后，安装项目所需的依赖：
cd my-taro-app
npm install这将根据 package.json 文件安装所有必要的依赖库。
4. 启动项目
请注意，为了满足多端打包的场景，将构建产物地址修改一下：
// config/index.ts
import { defineConfig, type UserConfigExport } from "@tarojs/cli";
import TsconfigPathsPlugin from "tsconfig-paths-webpack-plugin";
import devConfig from "./dev";
import prodConfig from "./prod";console.log("⚡ ~ process.env.TARO_ENV:", process.env.TARO_ENV);// https://taro-docs.jd.com/docs/next/config#defineconfig-辅助函数
export default defineConfig<"vite">(async (merge, { command, mode }) => {const baseConfig: UserConfigExport<"vite"> = {...,sourceRoot: "src",outputRoot: `dist/${process.env.TARO_ENV}`, // 指定多端}return baseConfig;
});(1). 网页端
项目搭建完成后，可以通过以下命令启动开发服务器：
pnpm dev:h5这条命令会启动 H5 端的开发环境，打开浏览器访问 http://localhost:10086，即可看到默认的 Taro 页面。
(2). 小程序
pnpm dev:weapp然后打开微信开发者工具，找到项目根目录下的 dist/weapp，导入即可。
1.3. 基础内容
1. 项目结构
创建完 Taro 项目后，项目结构大致如下：
my-taro-app/
├── config/ // 配置文件
├── node_modules/ // 项目依赖
├── src/ // 源码文件
│ ├── assets/ // 静态资源
│ ├── components/ // 自定义组件
│ ├── pages/ // 页面文件
│ ├── app.tsx // 应用入口文件
│ └── index.html // H5 页面模板
├── package.json // 项目描述及依赖
└── tsconfig.json // TypeScript 配置（如使用）2. 重要文件说明
app.tsx: 应用的入口文件，定义了应用的基本结构和状态管理。
pages/: 包含所有页面，每个页面都有一个对应的目录和文件。
components/: 存放自定义组件的地方，可以复用的 UI 元素都可以放在这里。
config/: 配置文件，包括路由、样式等。
2. Taro 常用组件
Taro 提供了一套跨平台的组件，以下是一些常用组件的详细介绍：
2.1. View
<View> 是 Taro 中最基本的布局组件，类似于 HTML 的 <div>。
import { View } from '@tarojs/components';const MyComponent = () => {return (<View style={{ padding: '20px' }}><Text>Hello, Taro!</Text></View>);
};2.2. Text
<Text> 用于显示文本，支持样式设置。
import { Text } from '@tarojs/components';const MyText = () => {return (<Text style={{ color: 'blue' }}>这是蓝色文本</Text>);
};2.3. Image
<Image> 用于显示图片，支持本地和网络图片。
import { Image } from '@tarojs/components';const MyImage = () => {return (<Image src="https://example.com/image.png" mode="aspectFit" />);
};2.4. Button
<Button> 用于创建按钮，支持多种样式和事件。
import { Button } from '@tarojs/components';const MyButton = () => {return (<Button onClick={() => Taro.showToast({ title: '按钮被点击' })}>点击我</Button>);
};2.5. Input
<Input> 用于获取用户输入，支持多种输入类型。
import { Input } from '@tarojs/components';const MyInput = () => {return (<Input placeholder="请输入内容" />);
};2.6. Form
<Form> 用于创建表单，支持多种表单控件。
import { Form, Button } from '@tarojs/components';const MyForm = () => {return (<Form onSubmit={(e) => { /* 处理提交 */ }}><Input name="username" placeholder="用户名" /><Button formType="submit">提交</Button></Form>);
};3. Taro 常用API
Taro 提供了一系列 API，方便开发者进行数据请求、设备信息获取等操作。
以下是一些常用 API 的介绍：
3.1. 网络请求
使用 Taro.request 进行网络请求，支持 GET 和 POST 等请求方式。
Taro.request({url: 'https://api.example.com/data',method: 'GET',success: (res) => {console.log(res.data);},fail: (error) => {console.error(error);}
});3.2. Toast 提示
使用 Taro.showToast 显示提示信息。
Taro.showToast({title: '操作成功',icon: 'success',duration: 2000,
});3.3. 获取设备信息
使用 Taro.getSystemInfoSync 获取设备信息。
const systemInfo = Taro.getSystemInfoSync();
console.log(systemInfo);3.4. 路由跳转
使用 Taro.navigateTo 进行页面跳转。
Taro.navigateTo({url: '/pages/detail/detail'
});3.5. 存储
使用 Taro.setStorageSync 和 Taro.getStorageSync 进行本地存储操作。
Taro.setStorageSync('key', 'value');
const value = Taro.getStorageSync('key');
console.log(value);4. 多端开发方案详解
Taro 的设计初衷就是为了统一跨平台的开发方式，通过运行时框架、组件和 API 来抹平多端差异。尽管如此，由于不同平台之间的差异，Taro 提供了多种方案来实现更好的跨平台开发，具体如下：
4.1. 内置环境变量
Taro 在编译时提供了一些内置环境变量，以帮助开发者进行特定的处理。
1. process.env.TARO_ENV
这个变量用于判断当前的编译平台类型，其取值包括：
weapp
swan
alipay
tt
qq
jd
h5
rn
通过这个变量，开发者可以在代码中区分不同环境，以使用不同的逻辑。
2. 引用不同资源
if (process.env.TARO_ENV === 'weapp') {require('path/to/weapp/name');
} else if (process.env.TARO_ENV === 'h5') {require('path/to/h5/name');
}3. 加载不同组件
<View>{process.env.TARO_ENV === 'weapp' && <ScrollViewWeapp />}{process.env.TARO_ENV === 'h5' && <ScrollViewH5 />}
</View>备注: 不要解构 process.env，请直接以完整方式使用 process.env.TARO_ENV。
4.2. 组件文件中的跨平台支持
为了方便编写跨端的组件代码，Taro 在 .vue 文件的 template 中支持条件编译的特性。
1. 指定平台保留样式
/* #ifdef %PLATFORM% */
模板代码
/* #endif */2. 指定平台剔除样式
/* #ifndef %PLATFORM% */
模板代码
/* #endif */示例：希望某段模板内容只在微信小程序中生效。
/* #ifdef weapp */
模板代码
/* #endif */多个平台可以用空格隔开。
4.3. 统一接口的多端文件
虽然内置环境变量可以解决大部分跨端问题，但代码中逻辑判断会影响可维护性。为此，Taro 提供了统一接口的多端文件的方式来解决跨端差异。
1. 统一接口文件的命名规则
开发者可以通过将文件命名为 原文件名 + 端类型 来创建不同端的实现。所有不同端的文件对外保持统一接口，引用时只需用默认文件名。
2. 使用要点
不同端的文件必须保持统一接口和调用方式。
引用文件时，只需使用默认文件名，不需带后缀。
最好有一个平台无关的默认文件，以避免 TypeScript 的报错。
3. 使用场景
多端组件
假设有一个 Test 组件，存在不同版本：
├── test.js // 默认版本
├── test.weapp.js // 微信小程序版本
├── test.swan.js // 百度小程序版本
└── test.h5.js // H5 版本引用方式：
import Test from '../../components/test';<Test argA={1} argB={2} />- 多端脚本逻辑
例如在微信小程序上使用 Taro.setNavigationBarTitle 设置页面标题，而 H5 使用 document.title，可以封装一个 setTitle 方法：
// set_title.weapp.js
import Taro from '@tarojs/taro';
export default function setTitle(title) {Taro.setNavigationBarTitle({ title });
}// set_title.h5.js
export default function setTitle(title) {document.title = title;
}// 调用
import setTitle from '../utils/set_title';
setTitle('页面标题');- 多端页面路由
根据不同平台设置不同的路由规则：
let pages = [];if (process.env.TARO_ENV === 'weapp') {pages = ['/pages/index/index'];
}if (process.env.TARO_ENV === 'swan') {pages = ['/pages/indexswan/indexswan'];
}export default {pages,
};4.4. 端平台插件
从 V3.1.0 起，Taro 将每个小程序平台的兼容逻辑抽取为 Taro 插件，以支持对应平台的编译。Web 端平台插件自 V3.6.0 开始支持。
1. Taro 内置的端平台插件
2. 其它端平台插件
3. 使用方法
配置插件：
// Taro 项目配置
module.exports = {plugins: ['@tarojs/plugin-platform-alipay-iot'],
};编译为支付宝 IOT 端小程序：
taro build --type iot
taro build --type iot --watch4.5. 端平台的插件化设计思想
随着小程序平台的不断发展，Taro 为了适应新兴平台的需求，提出了端平台的插件化设计思想。
这一思想旨在通过插件的形式扩展 Taro 的端平台支持能力，使得开发者能够灵活地添加或修改编译逻辑，而无需直接修改 Taro 核心库。
1. 插件化设计的理念
解耦合：插件化设计使得平台特定的编译逻辑与 Taro 的核心功能解耦。开发者可以根据自己的需求，选择性地加载所需的插件，而不影响 Taro 的其他部分。这种解耦合有助于提高代码的可维护性和可扩展性。
开放性：Taro 的插件系统允许社区和开发者根据不同的平台需求，自由开发和使用插件。这样的开放性不仅促进了插件的快速迭代和更新，也鼓励社区参与到框架的改进中来。
可复用性：通过插件化，开发者可以复用已有的插件，避免重复造轮子。比如，针对不同的小程序平台，开发者可以基于已有的插件进行扩展，只需实现特定的功能，而无需重新实现所有逻辑。
2. 插件的结构
每个插件通常由以下几个部分组成：
插件名称：唯一标识插件。
编译钩子：在编译过程中，Taro 会在特定的阶段调用插件提供的钩子，以允许开发者插入自定义的编译逻辑。
配置选项：插件可以通过配置选项，让用户定制插件的行为。
3. 插件的封装示例
以下是一个简单的自定义端平台插件的示例，用于扩展微信小程序的编译支持。
创建插件目录 @tarojs/plugin-weixin，并在其中添加以下文件：
@tarojs/plugin-weixin/
├── index.js
└── package.json编写 package.json
{"name": "@tarojs/plugin-weixin","version": "1.0.0","main": "index.js","taro": {"plugin": true}
}编写 index.js
老版本：
module.exports = (api) => {api.on('buildStart', () => {console.log('Custom Alipay plugin: Build started');});api.on('buildComplete', () => {console.log('Custom Alipay plugin: Build completed');});api.modifyWebpackConfig((config) => {// 可以对 Webpack 配置进行修改config.module.rules.push({test: /\.custom$/,use: 'custom-loader',});return config;});
};4.x：
export default (ctx, options) => {// plugin 主体ctx.onBuildStart(() => {console.log('编译开始！')})ctx.onBuildFinish(() => {console.log('Webpack 编译结束！')})ctx.onBuildComplete(() => {console.log('Taro 构建完成！')})
}4. 使用自定义插件
在 Taro 项目的配置文件中引入自定义插件：
// config/index.js
module.exports = {plugins: ['@tarojs/plugin-weixin'],
};5. 多端应用构建与发布
5.1. 微信小程序构建与发布
1. 构建微信小程序
在项目根目录下，使用以下命令构建微信小程序：
pnpm build:weapp构建成功后，生成的文件将位于 /dist/weapp 目录中。构建过程会将项目代码转换为微信小程序所需的格式，并进行优化。
2. 发布微信小程序
安装微信开发者工具：下载并安装 微信开发者工具。
打开微信开发者工具：启动工具，并选择“导入项目”。
选择构建目录：在导入项目时，选择刚才生成的
/dist/weapp目录。填写 AppID：如果尚未拥有 AppID，可以选择“无 AppID”进行测试。
上传代码：导入完成后，点击右上角的“上传”按钮，将代码上传至微信服务器。
提交审核：上传后，填写相关信息并提交审核，待审核通过后即可发布。
3. 注意事项
代码检查：在发布前，确保代码符合微信小程序的审核规范，避免因不合规导致审核失败。
AppID 管理：确保正确管理 AppID 和相关配置，避免信息泄露。
5.2. H5 应用构建与发布
1. 构建 H5 应用
在项目根目录下，使用以下命令构建 H5 应用：
pnpm build:h5构建成功后，生成的文件将位于 /dist/h5 目录中。
2. 发布 H5 应用
这部分部署工作跟其他实战项目操作类似，我们不详细展开，我们以 caddy 为例：
(1). 创建 Dockerfile
在 H5 应用的根目录下，创建一个名为 Dockerfile 的文件，内容如下：
# 使用 Caddy 官方镜像
FROM caddy:latest# 将构建的 H5 文件复制到 Caddy 的默认目录
COPY ./dist/h5 /usr/share/caddy(2). 目录结构示例
你的项目目录结构应该如下所示：
myProject/
├── dist/
│ └── h5/
│ ├── index.html
│ ├── assets/
│ └── ...
└── Dockerfile(3). 构建 Docker 镜像
在项目根目录下，执行以下命令构建 Docker 镜像：
docker build -t my-h5-app .这里 my-h5-app 是自定义的镜像名称。
(4). 运行 Docker 容器
使用以下命令运行 Docker 容器：
docker run -d -p 80:80 --name my-h5-app-container my-h5-app参数说明：
-d：以后台模式运行容器。
-p 80:80：将宿主机的 80 端口映射到容器的 80 端口。
--name my-h5-app-container：指定容器的名称。
(5). 访问应用
在浏览器中输入 http://<YOUR_SERVER_IP>，即可访问部署的 H5 应用。
(6). 配置 HTTPS（可选）
Caddy 默认支持自动获取 SSL 证书，但需要你提供域名。在使用 Caddy 时，你可以通过添加一个 Caddyfile 来配置 HTTPS。
- 创建 Caddyfile
在项目根目录下创建一个名为 Caddyfile 的文件，内容如下：
yourdomain.com {root * /usr/share/caddyfile_server
}将 yourdomain.com 替换为你的实际域名。
- 使用 Caddyfile 运行 Docker
使用以下命令重新运行 Docker 容器：
docker run -d -p 80:80 -p 443:443 --name my-h5-app-container -v $(pwd)/Caddyfile:/etc/caddy/Caddyfile my-h5-app