快速开始

从新项目开始，或把已有代码迁入红糖云服。先选一条适合你的路径，再完成一次“创建 → 构建 → 真机验证”。

你的起点	推荐入口
已有小程序、应用或游戏	AI 迁移教程
新建 React Native 小程序	本页 + TodoList 实战
保留 Taro 微信、H5 等多端代码	Taro 开发
新建或迁移 Godot 游戏	Godot 游戏实战
为项目接入宿主能力	JS SDK 指南

1. 准备环境

安装 Node.js、Git 和一种固定的包管理器。CLI 声明 Node.js 18 起，整个模板工具链可能要求更高版本；请同时满足模板中 React Native、Taro 等依赖的 engines。真机调试需要红糖云服客户端，手机能够访问电脑的调试服务。

node --version
git --version
npx --yes @htyf-mp/cli --help

本文命令要求 CLI 支持 init、build、debug 和 --project。若安装版本没有这些参数，请使用包含这些功能的发布版本，或克隆 htyf-cli 后安装依赖，使用 node /absolute/path/to/htyf-cli/packages/cli/src/index.mjs --help 检查源码入口。

2. 创建 RN 小程序

在准备存放项目的目录执行，目标 my-app 必须尚不存在：

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

初始化会生成项目标识与 app.json.htyf 配置。检查 package.json、入口文件和模板 README，再开始修改页面。目录名使用小写字母与连字符。

其他目标只需选择对应模板：

参数	模板内容
`--template app`	React Native 应用小程序
`--template taro`	Taro 的 HTYF 平台项目
`--template game`	Godot 游戏与 HTYF SDK

当前初始化菜单不提供 web-template。已有 Web 项目可查阅历史 Web 项目说明，新 Taro 项目请使用 taro 模板。

3. 构建资源包

在生成的 RN 项目根目录执行：

npx --yes @htyf-mp/cli build --non-interactive --version 1.0.0 --platform ios

首次构建提供版本号；之后省略 --version 可保留已有有效版本。Android 使用 --platform android。以 CLI 打印的构建产物路径为准，资源包是供宿主加载的包，并不是独立 APK 或 IPA。

按目标选择构建链

Taro 使用模板中的 npm run build:htyf，具体见 Taro 教程。Godot 使用目标版本引擎和导出流程。不要把 RN 的构建命令直接套到其他目标。

4. 真机调试

npx --yes @htyf-mp/cli debug --non-interactive --platform ios

保持服务运行，使用客户端扫描终端展示的二维码。若手机无法访问服务，先检查局域网地址、端口、防火墙与资源地址。桌面开发助手入口见开发助手。

验收时至少检查：页面能打开、关键交互可操作、返回导航正确、空数据和失败状态可见、胶囊与安全区没有遮住按钮。涉及原生 API 的功能需在宿主验证。

常用操作

npx --yes @htyf-mp/cli build --non-interactive --project /absolute/path/to/my-app --platform ios
 
# 同步依赖后重新安装；先检查版本变更
npx --yes @htyf-mp/cli sync-deps --non-interactive
 
# 清理当前项目的构建产物
npx --yes @htyf-mp/cli clean build --non-interactive

直接运行 npx @htyf-mp/cli 仍可进入交互菜单。历史菜单截图仅作界面参考，命令参数以当前 --help 为准。

下一步：AI 迁移 · Taro 开发 · 常见问题 · 仓库与贡献。