@htyf-mp/cli 0.2.19 → 0.2.20

package/README.md

@@ -1,21 +1,114 @@
-# 红糖云服app 小程序模板 CLI
+## 红糖云服小程序模板 CLI
 
-用于构建红糖云服小程序的前端框架模板
+用于创建和管理 **红糖云服 App 小程序** 项目（应用 / 游戏 / Web / 插件），包含：
 
-## 使用
+- 初始化小程序项目模版
+- 构建小程序资源包（打包）
+- 启动真机调试服务
+- 清理构建产物与临时文件
 
-生成一个新项目:
+- 官网：[`https://mp.dagouzhi.com/`](https://mp.dagouzhi.com/)
+- GitHub：[`https://github.com/htyf-mp-community`](https://github.com/htyf-mp-community)
 
-```sh
+## 安装与快速开始
+
+建议直接使用 npx：
+
+```bash
 npx @htyf-mp/cli
 ```
 
-接下来，使用CLI配置项目名和Appid，或者稍后再配置，最后选择模板类型
+按照交互提示完成：
+
+1. **输入应用目录名**（例如 `my-htyf-mp`，用于创建项目文件夹）。
+2. **输入应用显示名称**（2–4 个中文/字母/数字）。
+3. **选择模板类型**：
+   - `app-template`：React Native 应用小程序（对应 `type: 'app'`）。
+   - `game-template`：Godot 游戏小程序（对应 `type: 'game'`）。
+   - `web-template`：Web/H5 小程序（对应 `type: 'web'`）。
+4. 选择模板仓库镜像（当前默认使用 GitHub）。
+
+CLI 会自动：
+
+- 克隆官方模版仓库到临时目录。
+- 清理无关模版，仅保留所选模板。
+- 生成 `app.json` 中的 `htyf` 配置（包含 `appid`、`name`、`zipUrl`、`appUrlConfig` 等）。
+- 将模板拷贝到你指定的项目目录中。
+
+> 各模板的具体用法，请参考生成项目中 `_apps_temp_` / `_game_temp_` / `_web_temp_` 目录下的 `README.md`。
+
+## 项目操作命令
+
+进入生成好的项目根目录后，直接运行 CLI（支持 `node` 或已全局安装的命令）：
+
+### 交互式主菜单
+
+```bash
+node src/index.mjs
+```
+
+在交互菜单中可以选择：
+
+- 🆕 初始化新小程序项目（`init`）
+- 🔍 小程序 - 打包小程序（`mp-build`）
+- 📦 小程序 - 真机调试（`mp-debug`）
+- 🧹 清理模式 - 清理临时文件（`clean`）
+- 👋 退出
+
+### 构建小程序（打包）
+
+```bash
+node src/index.mjs
+```
+
+在菜单中选择 **“小程序 - 打包小程序”**：
+
+1. CLI 会读取项目根目录下 `app.json` 中的 `htyf` 配置。
+2. 自动检测是否为 Godot 项目（是否存在 `project.godot`）：
+   - 存在：按 **Godot 游戏** 流程打包。
+   - 不存在：按 **普通小程序（React Native / Web）** 流程打包。
+3. 提示输入版本号（默认在当前版本基础上自动 +1，例如 `1.0.0 -> 1.0.1`）。
+4. 更新 `app.json` 中的版本号并执行构建，将资源输出到 `dist` 目录。
+
+构建完成后，可以将产物上传到 `zipUrl` 指定的地址，供红糖云服 App 拉取与更新。
+
+### 真机调试
+
+在主菜单中选择 **“小程序 - 真机调试”**：
+
+- CLI 会启动调试服务器，更新 `app.json` 中的调试地址。
+- 在红糖云服 App 中配置好对应的调试入口，即可在真机上实时预览与调试。
+
+> 具体调试行为（如 QR 码、连接方式）以红糖云服 App 当前版本为准。
 
-### 运行应用程序
+### 清理命令
 
-进入`mini-apps-template`或`mini-game-template`目录并运行:
-> 具体模板使用，可参考模板内的README.md
-```sh
-npm start
+支持通过参数直接清理，无需进入交互界面：
+
+```bash
+node src/index.mjs --clean all     # 清理所有临时文件
+node src/index.mjs --clean build   # 清理构建输出
+node src/index.mjs --clean temp    # 清理临时目录
+node src/index.mjs --clean logs    # 清理日志文件
+node src/index.mjs --clean cache   # 清理缓存文件
 ```
+
+也可以在交互菜单中选择 **“清理模式 - 清理临时文件”**，按提示选择清理范围。
+
+## app.json 与 htyf 配置
+
+项目根目录下会有一个 `app.json`，其中包含 `htyf` 字段，CLI 会从这里读取并更新应用配置：
+
+- 重要字段包括：
+  - `type`: `'app' | 'game' | 'web' | 'plugin'`
+  - `appid`: 小程序唯一 ID
+  - `name`: 应用名称
+  - `zipUrl`: 构建产物 zip 包地址
+  - `appUrlConfig`: 线上配置地址
+  - `version`: 版本号（由 CLI 帮你自动递增或手动修改）
+
+> 不同模板下的 `app.json` 字段说明和推荐配置，可在各自模板目录的 README 中查看：  
+> - React Native 应用小程序：`_apps_temp_/README.md`  
+> - Godot 游戏小程序：`_game_temp_/README.md`  
+> - Web/H5 小程序：`_web_temp_/RADME.md`
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htyf-mp/cli",
-  "version": "0.2.19",
+  "version": "0.2.20",
   "description": "红糖云服app小程序模板-cli",
   "type": "module",
   "bin": {

package/src/build.mjs

@@ -8,6 +8,7 @@
 import path from 'path';
 import fse from 'fs-extra';
 import AdmZip from 'adm-zip';
+import QRCode from 'qrcode';
 import { fileURLToPath } from 'node:url';
 import { Logger } from './logger.mjs';
 import { CONSTANTS } from './constants.mjs';
@@ -22,6 +23,98 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PROJECT_ROOT = getProjectRoot();
 
+/**
+ * 复制目录内容（不包含最外层目录名）
+ * @param {string} srcDir
+ * @param {string} destDir
+ */
+async function copyDirContents(srcDir, destDir) {
+  await fse.ensureDir(destDir);
+  const entries = await fse.readdir(srcDir);
+  for (const entry of entries) {
+    await fse.copy(path.join(srcDir, entry), path.join(destDir, entry), { overwrite: true });
+  }
+}
+
+/**
+ * 执行 Web 端 H5 构建
+ * @param {'build'|'dev'} mode
+ */
+async function runWebH5Build(mode = 'build') {
+  const cmd = mode === 'dev' ? 'npm run dev:h5' : 'npm run build:h5';
+  Logger.info(`开始执行 Web H5 构建: ${cmd}`);
+  await CommandExecutor.execute(cmd, {
+    description: `Web H5 ${mode === 'dev' ? '开发' : '构建'}`,
+    timeout: mode === 'dev' ? 120000 : 300000,
+    showCommand: false,
+  });
+}
+
+/**
+ * 将 taro build:h5 的输出同步到最终 zip 目录
+ *
+ * 说明：
+ * - taro 的 outputRoot 在模板里通常是 ./dist
+ * - CLI 最终会把内容打包到 ./dist/dist（outputPath）
+ * - 因此这里需要把 ./dist 下的 h5 静态产物复制到 ./dist/dist
+ *
+ * @param {string} projectDistRoot - taro 输出目录（一般为 ./dist）
+ * @param {string} zipInputDir - zip 输入目录（一般为 ./dist/dist）
+ */
+async function syncWebH5Output(projectDistRoot, zipInputDir) {
+  // 先清空 zip 输入目录，避免残留
+  await fse.ensureDir(zipInputDir);
+  await fse.emptyDir(zipInputDir);
+
+  const h5Dir = path.join(projectDistRoot, 'h5');
+  if (await fse.pathExists(h5Dir)) {
+    Logger.info('检测到 taro H5 输出目录 ./dist/h5，复制其内容...');
+    await copyDirContents(h5Dir, zipInputDir);
+    return;
+  }
+
+  Logger.info('未检测到 ./dist/h5，尝试复制 ./dist 下的 H5 静态产物...');
+  const entries = await fse.readdir(projectDistRoot);
+
+  const excludeNames = new Set([
+    'dist', // 避免递归复制 ./dist/dist
+    'build', // RN bundle 输出目录
+    'app.json',
+    'manifest.json',
+  ]);
+
+  for (const entry of entries) {
+    if (excludeNames.has(entry)) continue;
+    if (entry.endsWith('.dgz')) continue;
+
+    await fse.copy(path.join(projectDistRoot, entry), path.join(zipInputDir, entry), { overwrite: true });
+  }
+}
+
+/**
+ * 在构建输出目录生成二维码图片
+ *
+ * 优先使用 zipUrl，若为空则回退到 appUrlConfig。
+ *
+ * @param {string} outputPath - 构建输出目录
+ * @param {object} appJson - 应用配置对象
+ * @returns {Promise<void>}
+ */
+async function generateBuildQrCode(outputPath, appJson) {
+  const qrContent = appJson?.zipUrl || appJson?.appUrlConfig;
+  if (!qrContent) {
+    Logger.warn('未配置 zipUrl/appUrlConfig，跳过二维码生成');
+    return;
+  }
+
+  const qrFilePath = path.join(outputPath, 'qrcode.png');
+  await QRCode.toFile(qrFilePath, qrContent, {
+    width: 320,
+    margin: 2
+  });
+  Logger.success(`二维码已生成: ${qrFilePath}`);
+}
+
 /**
  * 压缩文件夹为 ZIP 文件
  * 
@@ -116,13 +209,13 @@ export async function handleZip(inputPath, outputPath) {
  *   entry: './src/index.js'
  * }, false);
  */
-export async function mpBuildShell(newAppInfo, isGodot = false) {
+export async function mpBuildShell(newAppInfo, isGodot = false, buildOptions = {}) {
   Logger.info(`开始构建小程序包...`);
   Logger.info(`应用: ${newAppInfo.name}`);
   Logger.info(`应用ID: ${newAppInfo.appid}`);
   Logger.info(`版本: ${newAppInfo.version}`);
   Logger.info(`平台: ${CONSTANTS.BUNDLE_PLATFORM}`);
-  Logger.info(`项目类型: ${isGodot ? 'Godot 游戏' : '普通小程序'}`);
+  Logger.info(`项目类型: ${isGodot ? 'Godot 游戏' : (newAppInfo?.type === 'web' ? 'Web 应用' : '普通小程序')}`);
   
   // ========== 参数验证 ==========
   if (!newAppInfo.name || !newAppInfo.appid || !newAppInfo.version) {
@@ -148,6 +241,7 @@ export async function mpBuildShell(newAppInfo, isGodot = false) {
 
   // 构建 app.json 配置
   const appType = newAppInfo.type || (isGodot ? 'game' : 'app');
+  const isWeb = appType === 'web';
   const appJson = {
     ...newAppInfo,
     rotate: newAppInfo.rotate || 'portrait',
@@ -177,9 +271,11 @@ export async function mpBuildShell(newAppInfo, isGodot = false) {
   };
   Logger.info('mpOptions', mpOptions);
 
-  // 保存 app.json 到输出目录
   const appJsonPath = path.join(mpOutputPath, 'app.json');
-  await fse.writeJson(appJsonPath, appJson, { spaces: 2 });
+  // 注意：Web H5 构建会清理 ./dist，因此 app.json 写入要尽量晚一点
+  if (!isWeb) {
+    await fse.writeJson(appJsonPath, appJson, { spaces: 2 });
+  }
   const webpackConfigPath = path.join(__dirname, 'webpack.config.mjs');
 
   // ========== 清空输出目录 ==========
@@ -208,7 +304,6 @@ export async function mpBuildShell(newAppInfo, isGodot = false) {
 
   // ========== 执行构建 ==========
   try {
-    const isWeb = appType === 'web';
     if (!isGodot && !isWeb) {
       // ========== 普通小程序构建流程 ==========
       Logger.info('使用 React Native 构建小程序包...');
@@ -282,6 +377,21 @@ export async function mpBuildShell(newAppInfo, isGodot = false) {
       // 更新 app.json 中的 zipUrl
       appJson.zipUrl = newAppInfo.zipUrl || `${newAppInfo.host}/dist.${platformName}.dgz`;
       await fse.writeJson(appJsonPath, appJson, { spaces: 2 });
+    } else if (isWeb) {
+      // ========== Web 应用构建流程 ==========
+      // 正式打包走 build:h5；真机调试可通过 buildOptions.skipWebBuild 跳过
+      if (!buildOptions.skipWebBuild) {
+        await runWebH5Build('build');
+        await syncWebH5Output(mpOutputPath, outputPath);
+      } else {
+        Logger.info('跳过 Web H5 构建（debug 模式），仅打包 app.json');
+        // 保证 zipInputDir 存在，后续还要写 app.json/qrcode
+        await fse.ensureDir(outputPath);
+        await fse.emptyDir(outputPath);
+      }
+
+      // Web 构建后再写 app.json，避免被 taro 清理掉
+      await fse.writeJson(appJsonPath, appJson, { spaces: 2 });
     }
 
     // ========== 打包最终产物 ==========
@@ -291,6 +401,7 @@ export async function mpBuildShell(newAppInfo, isGodot = false) {
     if (!isGodot && appType !== 'web') {
       fse.copyFileSync(path.join(outputPath, '../manifest.json'), path.join(outputPath, 'manifest.json'));
     }
+    await generateBuildQrCode(outputPath, appJson);
 
     // 压缩输出目录为最终包
     const zipPath = await handleZip(outputPath, distPackagePath);

package/src/debug.mjs

@@ -13,9 +13,38 @@ import chalk from 'chalk';
 import boxen from 'boxen';
 import gradient from 'gradient-string';
 import { Logger } from './logger.mjs';
+import { CONSTANTS } from './constants.mjs';
 import { ConfigValidator } from './validators.mjs';
 import { mpBuildShell } from './build.mjs';
 import { printQrcode } from './utils-functions.mjs';
+import { spawn } from 'node:child_process';
+
+/**
+ * 等待 Web H5 首次编译产物就绪，避免 taro watch 后续清理 dist
+ * 导致最终缺少 dist/app.json 与 dist/dist.dgz。
+ *
+ * @param {{timeoutMs?: number, intervalMs?: number}} [options]
+ * @returns {Promise<boolean>}
+ */
+async function waitForWebH5Output(options = {}) {
+  const { timeoutMs = 120000, intervalMs = 1000 } = options;
+  const h5Dir = path.join(CONSTANTS.MP_OUTPUT_DIR, 'h5'); // ./dist/h5
+
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await fse.pathExists(h5Dir)) {
+      try {
+        const entries = await fse.readdir(h5Dir);
+        if (entries.length > 0) return true;
+      } catch (_) {
+        // directory may be in flux
+      }
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+
+  return false;
+}
 
 /**
  * 小程序真机调试
@@ -51,10 +80,27 @@ export async function mpDebugShell(newAppInfo, isGodot = false) {
     if (!isGodot && !isWeb && !newAppInfo.entry) {
       throw new Error('缺少必需的应用信息: entry');
     }
-    
+    let devH5Process = null;
+    if (isWeb) {
+      // devH5Process = spawn('npm', ['run', 'dev:h5'], {
+      //   stdio: 'inherit',
+      //   shell: true,
+      // });
+    }
+
+    // Web 真机调试：等待 taro 首次编译产物就绪
+    // 这样后续生成的 dist/app.json 与 dist/dist.dgz 不容易被覆盖/删除。
+    if (isWeb) {
+      Logger.info('等待 Web H5 首次编译完成...');
+      const ok = await waitForWebH5Output();
+      if (!ok) {
+        Logger.warn('等待 Web H5 产物超时，将继续生成调试用 dist 资源');
+      }
+    }
+
     // ========== 构建小程序包 ==========
     Logger.info('开始构建小程序包...');
-    const zipPath = await mpBuildShell(newAppInfo, isGodot);
+    const zipPath = await mpBuildShell(newAppInfo, isGodot, { skipWebBuild: isWeb });
     const assetsPath = path.dirname(zipPath);
     const appJsonPath = path.join(assetsPath, 'app.json');
 
@@ -71,6 +117,11 @@ export async function mpDebugShell(newAppInfo, isGodot = false) {
     const host = networkValidation.host;
     const port = await portfinder.getPortPromise();  // 自动查找可用端口
 
+    // Web 真机调试：启动 H5 dev server，并把固定地址写入打包后的 app.json 的 webUrl
+    // 注意：dev:h5 由 taro 侧负责启动静态服务（这里只启动命令并在 app.json 写死 URL）
+    const webDevUrl = process.env.WEB_H5_DEV_URL || 'http://192.168.1.28:10086';
+    
+
     // 创建静态文件服务器
     const app = superstatic.server({
       port: port,
@@ -96,6 +147,7 @@ export async function mpDebugShell(newAppInfo, isGodot = false) {
         "version": applocaljson.version,
         appUrlConfig: debugerAppUrlConfig,
         zipUrl: debugerZip,
+        ...(isWeb ? { webUrl: webDevUrl } : {}),
       };
 
       // 更新 app.json 文件，写入调试 URL
@@ -103,6 +155,7 @@ export async function mpDebugShell(newAppInfo, isGodot = false) {
         ...fse.readJSONSync(appJsonPath),
         appUrlConfig: debugerAppUrlConfig,
         zipUrl: debugerZip,
+        ...(isWeb ? { webUrl: webDevUrl } : {}),
       });
 
       // 生成调试二维码 URL
@@ -145,6 +198,20 @@ export async function mpDebugShell(newAppInfo, isGodot = false) {
     const handleShutdown = () => {
       Logger.info('\n正在关闭调试服务器...');
       let isClosed = false;
+
+      // 优先停止 Web H5 dev server（debug 进程）
+      if (devH5Process) {
+        try {
+          // detached 后它会成为新的进程组 leader，使用负 pid 可杀整个组
+          process.kill(-devH5Process.pid, 'SIGTERM');
+        } catch (e) {
+          try {
+            devH5Process.kill('SIGTERM');
+          } catch (_) {
+            // ignore
+          }
+        }
+      }
       
       // 尝试关闭服务器
       server.close(() => {