快速开始

从新建项目到使用

本文按 新建项目 → 开发运行 → 打包/真机调试 的顺序，带你快速走完一遍标准流程。

你可以按模板类型直接进入对应实战文档：

流程概览

每一步怎么判断“做对了”

新建项目

CLI 界面与流程（实拍）

在终端执行 npx @htyf-mp/cli 后，会看到 红糖云服 应用 CLI 工具 的交互界面（版本号以本地为准，例如 v2.2.0），并显示当前 项目目录。

主菜单常见选项如下：

选择 🆕 初始化新小程序项目 后，按提示填写应用程序目录名称、应用程序名称，再选择模板与镜像。下图示例：目录名 todolist，应用名 小程序，模板 app-template，镜像 GitHub (最新)（会显示「正在克隆模板仓库」）。

克隆完成后会提示 项目创建成功，并给出项目路径与下一步操作（以 CLI 实际输出为准），例如：

典型后续命令包括：

cd <你的目录名>    # 例如：cd todolist
npm install
npm run ios        # 或 npm run android

模板还会提示使用 npm run htyf 构建红糖云服小程序；需要查看详细日志时，可加 --debug（如 npx @htyf-mp/cli --debug）。

准备空目录

在一个空目录下打开终端（或确保当前目录下没有会冲突的已有项目）。
不要在已有 app.json 的目录里再次初始化。

运行 CLI 并选择初始化

在终端执行：

npx @htyf-mp/cli

进入交互式菜单后，选择 🆕 初始化新小程序项目。

按提示输入

根据提示依次填写：

完成

完成后，会在当前目录下生成同名文件夹，内含模板代码和已配置好的 app.json。

后续安装依赖、运行 iOS/Android、执行 npm run htyf 等，以 CLI 成功页提示 与 项目内 README 为准。

开发与运行

初始化完成后：

1. 进入项目目录
   例如：cd my-htyf-mp（以你填写的目录名为准）。

2. 按模板说明操作
   安装依赖、启动开发服务等，详见项目内的 README。

3. 确认在项目根
   当前目录需要有 app.json 且包含 htyf 配置，后续打包与真机调试才能被正确识别。

打包与真机调试

在项目根目录下执行：

npm run htyf

打包（产出 ZIP）

1. 选择 🔍 小程序 - 打包小程序。
2. 输入版本号（x.y.z），或直接回车，使用当前 app.json.htyf.version 自动递增。
3. 确认后会自动更新版本、执行构建，并输出 ZIP 文件（如 dist.*.dgz）。

真机调试（扫码访问）

1. 选择 📦 小程序 - 真机调试。
2. 输入版本号（规则同打包）。
3. 构建完成后会启动本地服务并显示二维码，手机扫码即可调试。

项目类型说明

• 普通小程序：无 project.godot，依赖 app.json.htyf.entry 等配置，由 Webpack 打 bundle 再打 ZIP。
• Godot 游戏：在当前目录或 project / game / godot 下存在 project.godot 时，按 Godot 流程导出并打 ZIP。

参考

CLI 菜单速查

运行 npx @htyf-mp/cli 后，菜单中的选项含义与执行位置如下：

清理

通过菜单：运行 CLI → 选择「🧹 清理模式 - 清理临时文件」→ 选择清理类型 → 确认。

通过命令行（不进入菜单）：

npx @htyf-mp/cli --clean all     # 全部
npx @htyf-mp/cli --clean build  # 仅构建（dist）
npx @htyf-mp/cli --clean temp   # 仅临时（.htyf）
npx @htyf-mp/cli --clean logs   # 仅日志（.htyf/.logs）
npx @htyf-mp/cli --clean cache  # 仅缓存

命令行参数

示例：npx @htyf-mp/cli --help、npx @htyf-mp/cli --debug --clean build

配置与目录

• 应用配置：构建与调试会读取当前目录下 app.json 中的 htyf 配置（如 name、appid、version、entry），初始化时已自动生成。
• 目录：构建产物在 dist（或配置的 extraChunksPath）；临时文件与日志在 .htyf、.htyf/.logs。

小结