快速开始

从新建项目到使用

本文按 新建项目 → 开发运行 → 打包/真机调试 的顺序，带你从零完成到上线的完整流程。

流程概览

新建项目

准备空目录

在一个空目录下打开终端。
不要在有 app.json 等已有项目的目录里做初始化。

运行 CLI 并选择初始化

在终端执行：

npx @htyf-mp/cli

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

按提示输入

根据提示依次填写：

完成

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

后续如何安装依赖、启动开发服务等，请查看该目录下的 README。

开发与运行

初始化完成后：

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

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

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

打包与真机调试

在项目根目录下执行：

npx @htyf-mp/cli

打包（产出 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。

小结