3. Taro 小程序开发

Taro 小程序开发流程

本文介绍如何用 taro-template 创建 Taro 4 + React + TypeScript 项目，并编译到红糖云服小程序（htyf 构建目标）。同一套代码还可继续构建微信小程序、H5，或打包为独立 React Native App。

适用模板

本篇面向 CLI 中的 taro-template。模板已预置 @htyf-mp/taro-plugin-platform 及完整 RN 编译依赖，无需手动组装工具链。
若只需 Taro 页面型 Web 小程序，可参考 Web 小程序 TodoList 流程演示（web-template）。

与 app-template 的区别

app-template：React Native 原生容器小程序，适合 Tab/导航改造与原生能力接入。
taro-template：Taro 4 跨端项目，一套代码可编译到红糖云服、微信、H5，也可独立打包 iOS/Android App。

流程总览

阶段	操作
1. 初始化项目	空目录执行 `npx @htyf-mp/cli`，选择 `taro-template`
2. 安装依赖	进入项目目录后 `npm install`
3. 红糖云服端开发	`npm run dev:htyf` 监听构建
4. 真机调试	项目根 `npm run htyf` → 选择「小程序 - 真机调试」→ 扫码
5. 生产构建	`npm run build:htyf` 或 CLI 打包

1) 用 CLI 创建 taro-template 项目

在空目录执行：

npx @htyf-mp/cli

按提示选择并填写：

选择：🆕 初始化新小程序项目
模板类型：taro-template
应用程序目录名称：例如 my-taro-app
应用程序名称：例如 我的小程序
模板镜像：例如 GitHub (最新)

完成后进入目录并安装依赖：

cd my-taro-app
npm install

启动红糖云服端开发构建：

npm run dev:htyf

2) 常用构建命令

命令	说明
`npm run dev:htyf`	红糖云服小程序监听构建
`npm run build:htyf`	红糖云服小程序生产构建
`npm run dev:weapp`	微信小程序监听构建
`npm run build:weapp`	微信小程序生产构建
`npm run dev:h5`	H5 监听构建
`npm run build:h5`	H5 生产构建
`npm run ios`	运行 iOS 独立 App
`npm run android`	运行 Android 独立 App

红糖云服端使用 React Native 和 Metro，其他小程序及 H5 使用 Taro Webpack。模板已处理两套构建链的 React 版本差异，业务代码应优先使用 React 18 和 React 19 共有的 API。

3) 平台判断与扩展 API

平台专属代码可通过环境变量判断：

if (process.env.TARO_ENV === 'htyf') {
  // 红糖云服端专属逻辑
}

红糖云服扩展 API 通过 Taro.htyf 调用（具体能力见 JS SDK 使用指南）。

4) 在现有 Taro 项目中接入

安装平台插件和所需的 @htyf-mp/* 运行时后，在 Taro 项目配置中注册插件：

export default defineConfig({
  plugins: [
    '@htyf-mp/taro-plugin-platform'
  ],
  htyf: {
    appName: 'apps',
    entry: 'app',
    output: {}
  }
})

随后可以使用 Taro CLI 编译红糖云服端：

taro build --type htyf
taro build --type htyf --watch

版本配套

推荐从 taro-template 创建项目，以确保 React、React Native、Metro 和 @htyf-mp/* 的版本配套。现有项目接入时需自行检查依赖兼容性。

5) 真机调试与打包

在项目根（含 app.json 且配置了 htyf 字段）执行：

npm run htyf

真机调试：选择「📦 小程序 - 真机调试」→ 输入版本 → 扫码
打包：选择「🔍 小程序 - 打包小程序」→ 输入版本 → 得到 dist.*.dgz

6) CLI 常用参数

npx @htyf-mp/cli --sync-deps    # 同步项目依赖版本
npx @htyf-mp/cli --clean all    # 清理全部生成文件
npx @htyf-mp/cli --clean build  # 清理 dist 构建产物
npx @htyf-mp/cli --clean temp   # 清理 .htyf 临时目录
npx @htyf-mp/cli --debug        # 输出调试日志

参考链接

GitHub：htyf-mp-community
npm：@htyf-mp
快速开始：从新建项目到使用
常见问题：FAQ

3. Taro 小程序开发

On this page