Taro 跨端开发

使用 Taro 4、React 和 TypeScript 编写业务，通过 htyf 构建目标接入红糖云服。编译链、组件、运行时、样式工具和 templates/taro 模板由 htyf-taro 独立维护。

1. 创建项目

先按快速开始准备 Node.js、Git 和 CLI。检查 --help 后执行：

npx --yes @htyf-mp/cli init --non-interactive \
  --name my-taro-app --display-name 我的应用 --template taro
cd my-taro-app
npm install

支持新布局的 CLI 从 htyf-taro/templates/taro 创建项目。旧 npm 版本仍可能指向旧模板位置；需要最新逻辑时使用当前 CLI 源码入口。直接运行 npx @htyf-mp/cli 也可通过交互菜单选择 taro-template。

2. 从平台菜单开始开发

npm run dev:htyf

当前平台插件会显示操作菜单：

菜单项	实际行为
红糖小程序 - 本地开发	开启监听，编译页面和资源
红糖小程序 - 真机调试	确认版本、构建资源包、启动服务并显示二维码
红糖小程序 - 打包小程序	确认版本、构建并生成资源包
同步依赖版本	调整项目依赖版本，之后需要重新安装

CLI 与 Taro 平台插件是不同入口

CLI 的 init/build/debug 支持非交互调用；当前 Taro 平台插件内部仍使用交互菜单，npm run build:htyf 也会进入菜单。不要将它当作已经支持无人值守的 CI 命令，也不要给它直接套用 RN CLI 参数。由 AI 执行迁移时，需要明确记录这一步的人工操作或项目已有的自动化构建方式。

3. 配置宿主身份和资源地址

检查项目根的 htyf.config.json。Taro 打包逻辑从这里读取 appid、name、assetsHost，版本来自 package.json.version；初始化生成的 app.json.htyf 不能代替这份 Taro 打包配置。

{
  "name": "my-taro-app",
  "appid": "你的应用标识",
  "assetsHost": "https://你的资源域名/应用目录"
}

在原文件中更新对应字段，保留其他模板配置。使用初始化生成的应用标识，发布时填入真实资源域名。调试菜单会生成本地服务地址，发布资源地址则需要你配置可访问的存储服务。

4. 平台文件与 API

通用代码保留在普通文件中，HTYF 专属组件、逻辑或样式使用 .htyf.*：

src/components/Button/index.tsx
src/components/Button/index.htyf.tsx
src/components/Button/index.less
src/components/Button/index.htyf.less

平台判断与 Taro 配置：

if (process.env.TARO_ENV === 'htyf') {
  // 在这里接入 HTYF 专属行为
}

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

保留编译器必要的 RN 兼容选项，不要把所有 rn 字样机械替换为 htyf。扩展宿主 API 参照 JS SDK 指南，并以运行时实际暴露的接口为准。

5. 真机验收与产物

在 HTYF 平台菜单选择“真机调试”，完成版本输入并等待二维码。手机需要能访问电脑的服务地址。选择“打包小程序”时，当前实现将最终配置和资源包写入 dist_htyf/，包括 app.json 与 dist.dgz；以终端输出为准。

检查返回导航、异步状态、权限、弹层、Safe Area 和胶囊避让。资源包供红糖云服宿主运行，不能作为独立 APK/IPA 安装。

6. 其他平台

命令	目标
`npm run dev:weapp` / `npm run build:weapp`	微信小程序
`npm run dev:h5` / `npm run build:h5`	H5
`npm run ios` / `npm run android`	配套原生工程的独立 App

HTYF 使用 RN/Metro 及平台打包流程，微信和 H5 使用相应 Taro 工具链。模板包含不同 React 版本的适配，业务优先使用共有 API。独立 App 需要 Xcode 或 Android 工具链，其他端也需要分别验证。

7. 迁移已有项目

安装 htyf-migration Skill，在请求中明确“使用 Taro 模板”。先盘点页面、路由和 API，再以模板为基础逐项迁移。保留微信和 H5 的原有行为，HTYF 差异集中在平台文件及配置中。

源项目更新后可根据上次记录增量同步；构建通过后仍需进行宿主验收。仓库职责与版本关系见仓库与贡献。