@htyf-mp/cli 0.2.0-alpha.9 → 0.2.1

package/package.json

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

package/src/HtyfImportsPlugin.mjs

@@ -1,7 +1,6 @@
 import path from 'node:path';
 import fse from 'fs-extra';
 import { fileURLToPath } from 'node:url';
-import { getOptions } from 'loader-utils';
 
 // ==================== 常量定义 ====================
 const __dirname = path.dirname(fileURLToPath(import.meta.url));

package/src/build.mjs

@@ -1,3 +1,10 @@
+/**
+ * 构建模块
+ * 负责小程序和 Godot 游戏的打包构建
+ * 
+ * @module build
+ */
+
 import path from 'path';
 import fse from 'fs-extra';
 import AdmZip from 'adm-zip';
@@ -10,29 +17,40 @@ import { getMiniAppScriptId } from './utils-functions.mjs';
 import { getProjectRoot, guessGodotProjectDir } from './utils.mjs';
 import { exportGodot, promptGodotOptions } from './export_godot.mjs';
 
+// 获取当前文件所在目录
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PROJECT_ROOT = getProjectRoot();
 
 /**
- * 压缩文件夹为zip文件
- * @param {string} inputPath - 输入路径
- * @param {string} outputPath - 输出路径
- * @returns {Promise<string>} 压缩包路径
+ * 压缩文件夹为 ZIP 文件
+ * 
+ * 将指定目录压缩为 ZIP 格式，自动过滤 .map 文件（源码映射文件）
+ * 
+ * @param {string} inputPath - 要压缩的目录路径
+ * @param {string} outputPath - 输出的 ZIP 文件路径
+ * @returns {Promise<string>} 压缩包完整路径
+ * @throws {Error} 当输入路径不存在或不是目录时抛出错误
+ * 
+ * @example
+ * const zipPath = await handleZip('./dist', './dist.dgz');
  */
 export async function handleZip(inputPath, outputPath) {
   Logger.info(`开始压缩文件夹: ${inputPath}`);
   Logger.info(`输出文件: ${outputPath}`);
 
+  // 验证输入路径是否存在
   if (!(await fse.pathExists(inputPath))) {
     throw new Error(`输入路径不存在: ${inputPath}`);
   }
 
+  // 验证是否为目录
   const stats = await fse.stat(inputPath);
   if (!stats.isDirectory()) {
     throw new Error(`输入路径不是目录: ${inputPath}`);
   }
 
+  // 检查目录是否为空
   const files = await fse.readdir(inputPath);
   Logger.debug(`目录内容: ${files.length} 个文件/文件夹`);
 
@@ -44,6 +62,7 @@ export async function handleZip(inputPath, outputPath) {
   const admzip = new AdmZip();
 
   try {
+    // 添加目录到 ZIP，过滤 .map 文件（源码映射文件，不需要打包）
     await admzip.addLocalFolderPromise(inputPath, {
       filter: (filename) => {
         if (filename.endsWith('.map')) {
@@ -55,9 +74,11 @@ export async function handleZip(inputPath, outputPath) {
       }
     });
 
+    // 写入 ZIP 文件
     await admzip.writeZipPromise(zipPath);
     Logger.success(`压缩完成: ${zipPath}`);
 
+    // 显示压缩包大小
     const zipStats = await fse.stat(zipPath);
     Logger.info(`ZIP文件大小: ${FileSystemUtils.formatFileSize(zipStats.size)}`);
 
@@ -70,37 +91,64 @@ export async function handleZip(inputPath, outputPath) {
 
 /**
  * 构建小程序包
- * @param {object} newAppInfo - 应用信息
- * @returns {Promise<string>} 压缩包路径
+ * 
+ * 支持两种类型的项目构建：
+ * 1. 普通小程序项目：使用 webpack 打包
+ * 2. Godot 游戏项目：使用 Godot 导出工具打包
+ * 
+ * @param {object} newAppInfo - 应用信息对象
+ * @param {string} newAppInfo.name - 应用名称
+ * @param {string} newAppInfo.appid - 应用ID
+ * @param {string} newAppInfo.version - 应用版本
+ * @param {string} [newAppInfo.entry] - 入口文件（普通小程序必需）
+ * @param {string} [newAppInfo.host] - 服务器地址
+ * @param {string} [newAppInfo.appUrlConfig] - 应用配置URL
+ * @param {string} [newAppInfo.zipUrl] - 压缩包URL
+ * @param {boolean} [isGodot=false] - 是否为 Godot 项目
+ * @returns {Promise<string>} 压缩包完整路径
+ * @throws {Error} 当必需字段缺失或构建失败时抛出错误
+ * 
+ * @example
+ * const zipPath = await mpBuildShell({
+ *   name: '我的应用',
+ *   appid: 'com.example.app',
+ *   version: '1.0.0',
+ *   entry: './src/index.js'
+ * }, false);
  */
-export async function mpBuildShell(newAppInfo, isGodot) {
+export async function mpBuildShell(newAppInfo, isGodot = false) {
   Logger.info(`开始构建小程序包...`);
   Logger.info(`应用: ${newAppInfo.name}`);
   Logger.info(`应用ID: ${newAppInfo.appid}`);
   Logger.info(`版本: ${newAppInfo.version}`);
   Logger.info(`平台: ${CONSTANTS.BUNDLE_PLATFORM}`);
+  Logger.info(`项目类型: ${isGodot ? 'Godot 游戏' : '普通小程序'}`);
   
-  // 验证必需字段
+  // ========== 参数验证 ==========
   if (!newAppInfo.name || !newAppInfo.appid || !newAppInfo.version) {
     throw new Error('缺少必需的应用信息: name, appid, version');
   }
   
-  // 创建临时目录
+  // ========== 目录准备 ==========
+  // 创建临时目录（用于存放构建过程中的临时文件）
   const tempPath = CONSTANTS.TEMP_DIR;
   if (!FileSystemUtils.ensureDirectory(tempPath)) {
     throw new Error('无法创建临时目录');
   }
 
+  // 创建输出目录（最终构建产物存放位置）
   const mpOutputPath = CONSTANTS.MP_OUTPUT_DIR;
   if (!FileSystemUtils.ensureDirectory(mpOutputPath)) {
     throw new Error('无法创建输出目录');
   }
 
+  // ========== 应用配置准备 ==========
   const { version, appid } = newAppInfo;
   const scriptName = getMiniAppScriptId(appid, version);
 
+  // 构建 app.json 配置
   const appJson = {
-    type: 'app',
+    type: isGodot ? 'game' : 'app',  // Godot 项目类型为 'game'，普通小程序为 'app'
     engines: '2.0.0',
     name: newAppInfo.name,
     appid,
@@ -109,55 +157,105 @@ export async function mpBuildShell(newAppInfo, isGodot) {
     zipUrl: newAppInfo.zipUrl || `${newAppInfo.host}/dist.dgz`
   };
   
-  let outputPath = path.join(mpOutputPath, 'dist');
-  const distPackagePath = path.join(mpOutputPath, 'dist.dgz');
+  // 输出路径配置
+  let outputPath = path.join(mpOutputPath, 'dist');  // 最终输出目录
+  let distPackagePath = path.join(mpOutputPath, 'dist.dgz');  // 最终压缩包路径
   const rootIndexPath = path.join(tempPath, '..', 'index.js');
-
+  // Webpack 构建选项（仅普通小程序使用）
   const mpOptions = {
     name: scriptName,
     filename: `${scriptName}.bundle`,
     exposes: {
       'App': newAppInfo.entry,
     },
-    outputPath: path.join(mpOutputPath, 'build'),
+    outputPath: path.join(mpOutputPath, 'build'),  // webpack 构建输出目录
     extraChunksPath: outputPath,
-    manifest: path.join(mpOutputPath, 'build'),
+    manifest: path.join(mpOutputPath, 'manifest.json'),
   };
+  Logger.info('mpOptions', mpOptions);
 
+  // 保存 app.json 到输出目录
   const appJsonPath = path.join(mpOutputPath, 'app.json');
   await fse.writeJson(appJsonPath, appJson, { spaces: 2 });
   const webpackConfigPath = path.join(__dirname, 'webpack.config.mjs');
 
+  // ========== 清空输出目录 ==========
+  // 确保每次构建都是干净的状态，避免旧文件残留
+  Logger.info('清空输出目录...');
+  await fse.ensureDir(outputPath);
+  await fse.emptyDir(outputPath);
+  
+  // 清空 webpack 构建目录
+  // 如果 buildPath 是一个文件，先删除它，然后创建目录
+  const buildPath = path.join(mpOutputPath, 'build');
+  if (await fse.pathExists(buildPath)) {
+    const stats = await fse.stat(buildPath);
+    if (stats.isFile()) {
+      // 如果是文件，删除它
+      await fse.remove(buildPath);
+      Logger.info(`已删除文件: ${buildPath}`);
+    }
+    // 确保是目录并清空
+    await fse.ensureDir(buildPath);
+    await fse.emptyDir(buildPath);
+  } else {
+    // 如果不存在，直接创建目录
+    await fse.ensureDir(buildPath);
+  }
 
+  // ========== 执行构建 ==========
   try {
     if (!isGodot) {
+      // ========== 普通小程序构建流程 ==========
+      Logger.info('使用 Webpack 构建小程序包...');
       const command = `npx cross-env APP_ROOT_INDEX_PATH=${rootIndexPath} APP_EXPOSES_OPTIONS=${encodeURI(JSON.stringify(mpOptions))} webpack --config ${webpackConfigPath}`;
       await CommandExecutor.execute(command, {
         description: '构建小程序包',
-        timeout: 120000,
+        timeout: 120000,  // 2 分钟超时
         showCommand: false
       });
     } else {
+      // ========== Godot 游戏构建流程 ==========
       Logger.info('检测到 Godot 项目，开始执行 Godot 导出流程...');
+      
+      // 根据平台常量确定默认平台
       const defaultPlatform = ['android', 'ios'].includes(CONSTANTS.BUNDLE_PLATFORM) 
         ? CONSTANTS.BUNDLE_PLATFORM 
         : 'ios';
+      
+      // 准备 Godot 导出选项的默认值
       const godotDefaults = {
         targetBaseDir: outputPath,
         projectDir: guessGodotProjectDir(PROJECT_ROOT),
-        name: newAppInfo.name || 'GodotApp',
+        name: newAppInfo.appid || 'GodotApp',
         preset: defaultPlatform === 'android' ? 'Android' : 'iOS',
         platform: defaultPlatform
       };
+      
+      // 提示用户输入或确认 Godot 导出选项
       const godotOptions = await promptGodotOptions(godotDefaults);
       outputPath = path.resolve(godotOptions.targetBaseDir);
       await fse.ensureDir(outputPath);
-      await fse.emptyDir(outputPath);
+      
+      // 执行 Godot 导出
       await exportGodot(godotOptions);
+      
+      // Godot 项目使用平台特定的文件名（如 dist.ios.dgz 或 dist.android.dgz）
+      const platformName = godotOptions.platform === 'ios' ? 'ios' : 'android';
+      distPackagePath = path.join(mpOutputPath, `dist.${platformName}.dgz`);
+      
+      // 更新 app.json 中的 zipUrl
+      appJson.zipUrl = newAppInfo.zipUrl || `${newAppInfo.host}/dist.${platformName}.dgz`;
+      await fse.writeJson(appJsonPath, appJson, { spaces: 2 });
     }
 
+    // ========== 打包最终产物 ==========
+    // 将 app.json 复制到输出目录
     await fse.ensureDir(outputPath);
     await fse.copy(appJsonPath, path.join(outputPath, 'app.json'));
+    fse.copyFileSync(path.join(outputPath, '../manifest.json'), path.join(outputPath, 'manifest.json'));
+
+    // 压缩输出目录为最终包
     const zipPath = await handleZip(outputPath, distPackagePath);
     Logger.success(`压缩包已创建: ${zipPath}`);
     return zipPath;

package/src/debug.mjs

@@ -1,3 +1,10 @@
+/**
+ * 调试模块
+ * 负责启动小程序真机调试服务器
+ * 
+ * @module debug
+ */
+
 import path from 'path';
 import fse from 'fs-extra';
 import superstatic from 'superstatic';
@@ -12,45 +19,76 @@ import { printQrcode } from './utils-functions.mjs';
 
 /**
  * 小程序真机调试
+ * 
+ * 功能流程：
+ * 1. 构建小程序包
+ * 2. 验证网络配置
+ * 3. 启动本地调试服务器
+ * 4. 生成调试二维码
+ * 
  * @param {object} newAppInfo - 应用信息
+ * @param {string} newAppInfo.name - 应用名称
+ * @param {string} newAppInfo.appid - 应用ID
+ * @param {string} newAppInfo.version - 应用版本
+ * @param {string} [newAppInfo.entry] - 入口文件（普通小程序必需，Godot 项目不需要）
+ * @param {boolean} [isGodot=false] - 是否为 Godot 项目
+ * @throws {Error} 当必需字段缺失或网络配置验证失败时抛出错误
+ * 
+ * @example
+ * await mpDebugShell({
+ *   name: '我的应用',
+ *   appid: 'com.example.app',
+ *   version: '1.0.0',
+ *   entry: './src/index.js'
+ * }, false);
  */
-export async function mpDebugShell(newAppInfo) {
+export async function mpDebugShell(newAppInfo, isGodot = false) {
   try {
-    // 验证必需字段
-    if (!newAppInfo.entry) {
+    // ========== 参数验证 ==========
+    // Godot 项目不需要 entry 字段，普通小程序需要
+    if (!isGodot && !newAppInfo.entry) {
       throw new Error('缺少必需的应用信息: entry');
     }
     
-    const zipPath = await mpBuildShell(newAppInfo);
+    // ========== 构建小程序包 ==========
+    Logger.info('开始构建小程序包...');
+    const zipPath = await mpBuildShell(newAppInfo, isGodot);
     const assetsPath = path.dirname(zipPath);
     const appJsonPath = path.join(assetsPath, 'app.json');
 
     Logger.info(`资源路径: ${assetsPath}`);
     const applocaljson = fse.readJsonSync(appJsonPath);
 
-    // 验证网络配置
+    // ========== 网络配置验证 ==========
     const networkValidation = await ConfigValidator.validateNetworkConfig();
     if (!networkValidation.isValid) {
       throw new Error(`网络配置验证失败: ${networkValidation.error}`);
     }
 
+    // ========== 启动调试服务器 ==========
     const host = networkValidation.host;
-    const port = await portfinder.getPortPromise();
+    const port = await portfinder.getPortPromise();  // 自动查找可用端口
 
+    // 创建静态文件服务器
     const app = superstatic.server({
       port: port,
       address: host,
-      cwd: assetsPath
+      cwd: assetsPath  // 服务器根目录
     });
 
+    // 启动服务器
     const server = app.listen(function () {
       const address = server.address();
 
+      // ========== 生成调试配置 ==========
+      // 构建调试用的 URL
       const debugerAppUrlConfig = `http://${host}:${address.port}/app.json`;
       const debugerZip = `http://${host}:${address.port}/dist.dgz`;
+      
+      // 构建调试参数
       const args = {
         ...applocaljson,
-        development: true,
+        development: true,  // 标记为开发模式
         "name": applocaljson.name,
         "appid": applocaljson.appid,
         "version": applocaljson.version,
@@ -58,15 +96,17 @@ export async function mpDebugShell(newAppInfo) {
         zipUrl: debugerZip,
       };
 
+      // 更新 app.json 文件，写入调试 URL
       fse.writeJSONSync(appJsonPath, {
         ...fse.readJSONSync(appJsonPath),
         appUrlConfig: debugerAppUrlConfig,
         zipUrl: debugerZip,
       });
 
+      // 生成调试二维码 URL
       const qrcodeUrl = `https://share.dagouzhi.com/#/pages/index/index?data=${encodeURIComponent(JSON.stringify(args))}`;
 
-      // 显示调试信息
+      // ========== 显示调试信息 ==========
       console.log('\n');
       console.log(boxen(
         gradient.rainbow('小程序真机调试') + '\n\n' +
@@ -82,23 +122,29 @@ export async function mpDebugShell(newAppInfo) {
         }
       ));
 
+      // 显示调试配置 JSON
       console.log('\n' + chalk.yellow('调试配置:'));
       console.log(JSON.stringify(args, undefined, 2));
 
+      // 显示调试链接
       console.log('\n' + chalk.green('调试链接:'));
       console.log(qrcodeUrl);
 
+      // 显示二维码
       console.log('\n' + chalk.blue('二维码:'));
       printQrcode(qrcodeUrl);
 
       Logger.info('调试服务器已启动，按 Ctrl+C 停止');
     });
 
-    // 优雅关闭 - 移除全局处理，添加专用的服务器关闭处理
+    // ========== 优雅关闭处理 ==========
+    // 移除全局的信号处理，添加专用的服务器关闭处理
+    // 这样可以确保服务器能够正确关闭，避免资源泄漏
     const handleShutdown = () => {
       Logger.info('\n正在关闭调试服务器...');
       let isClosed = false;
       
+      // 尝试关闭服务器
       server.close(() => {
         if (!isClosed) {
           isClosed = true;
@@ -108,6 +154,7 @@ export async function mpDebugShell(newAppInfo) {
       });
       
       // 如果服务器在 3 秒内没有关闭，强制退出
+      // 防止服务器关闭卡死导致进程无法退出
       setTimeout(() => {
         if (!isClosed) {
           isClosed = true;
@@ -117,12 +164,12 @@ export async function mpDebugShell(newAppInfo) {
       }, 3000);
     };
 
-    // 移除全局的信号处理，添加专用的服务器关闭处理
-    // 这样可以确保服务器能够正确关闭
+    // 注册信号处理器
+    // 移除可能存在的全局处理器，避免冲突
     process.removeAllListeners('SIGINT');
     process.removeAllListeners('SIGTERM');
-    process.once('SIGINT', handleShutdown);
-    process.once('SIGTERM', handleShutdown);
+    process.once('SIGINT', handleShutdown);   // Ctrl+C
+    process.once('SIGTERM', handleShutdown);  // 终止信号
 
   } catch (error) {
     Logger.error(`小程序调试失败: ${error.message}`);

package/src/export_godot.mjs

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
 
+/**
+ * Godot 导出模块
+ * 负责处理 Godot 游戏项目的导出和打包
+ * 
+ * @module export_godot
+ */
+
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { accessSync, constants as fsConstants } from 'node:fs';
@@ -10,38 +17,71 @@ import AdmZip from 'adm-zip';
 import { execa } from 'execa';
 import inquirer from 'inquirer';
 
+// ========== 常量定义 ==========
+
+/** Godot 编辑器默认路径（macOS） */
 const DEFAULT_GODOT_BIN = '/Applications/Godot.app/Contents/MacOS/Godot';
+
+/** Godot 配置缓存目录 */
 const GODOT_CACHE_DIR = path.join(homedir() || process.cwd(), '.htyf');
+
+/** Godot 配置缓存文件路径 */
 const GODOT_CACHE_FILE = path.join(GODOT_CACHE_DIR, 'godot-config.json');
 
+/** 支持的平台枚举 */
 const PLATFORMS = {
   IOS: 'ios',
   ANDROID: 'android'
 };
 
+/** 平台预设名称映射 */
 const PRESET_NAMES = {
   [PLATFORMS.IOS]: 'iOS',
   [PLATFORMS.ANDROID]: 'Android'
 };
 
+/**
+ * 提示用户输入或确认 Godot 导出选项
+ * 
+ * 如果所有必需参数都已提供，则直接返回，不进行交互式询问
+ * 否则通过命令行交互获取用户输入
+ * 
+ * @param {object} [defaults={}] - 默认选项
+ * @param {string} [defaults.targetBaseDir] - 导出目标根目录
+ * @param {string} [defaults.projectDir] - Godot 项目目录
+ * @param {string} [defaults.appid] - 应用ID（用作导出文件名）
+ * @param {string} [defaults.preset] - Godot 导出预设名称
+ * @param {string} [defaults.platform] - 导出平台（'ios' 或 'android'）
+ * @returns {Promise<object>} Godot 导出选项对象
+ * 
+ * @example
+ * const options = await promptGodotOptions({
+ *   targetBaseDir: './dist',
+ *   projectDir: './game',
+ *   appid: 'com.example.game',
+ *   preset: 'iOS',
+ *   platform: 'ios'
+ * });
+ */
 export async function promptGodotOptions(defaults = {}) {
-  // 如果所有必需的值都已提供，直接返回，不进行询问
+  // 如果所有必需的值都已提供，直接返回，不进行询问（用于自动化场景）
   if (
     defaults.targetBaseDir &&
     defaults.projectDir &&
-    defaults.name &&
+    defaults.appid &&
     defaults.preset &&
     defaults.platform
   ) {
     return {
       targetBaseDir: String(defaults.targetBaseDir).trim(),
       projectDir: String(defaults.projectDir).trim(),
-      name: String(defaults.name).trim(),
+      name: String(defaults.appid).trim(),
       preset: String(defaults.preset).trim(),
       platform: defaults.platform
     };
   }
 
+  // 通过交互式命令行获取用户输入
   const answers = await inquirer.prompt([
     {
       type: 'input',
@@ -92,6 +132,12 @@ export async function promptGodotOptions(defaults = {}) {
   };
 }
 
+/**
+ * 检查文件是否可执行
+ * 
+ * @param {string} filePath - 文件路径
+ * @returns {boolean} 文件是否可执行
+ */
 function isExecutable(filePath) {
   if (!filePath) return false;
   if (!fs.existsSync(filePath)) return false;
@@ -104,6 +150,11 @@ function isExecutable(filePath) {
   }
 }
 
+/**
+ * 读取缓存的 Godot 编辑器路径
+ * 
+ * @returns {string} 缓存的路径，如果不存在则返回空字符串
+ */
 function readCachedGodotPath() {
   try {
     if (!fs.existsSync(GODOT_CACHE_FILE)) {
@@ -116,15 +167,26 @@ function readCachedGodotPath() {
   }
 }
 
+/**
+ * 保存 Godot 编辑器路径到缓存
+ * 
+ * @param {string} godotPath - Godot 编辑器路径
+ */
 async function writeCachedGodotPath(godotPath) {
   try {
     await fs.ensureDir(GODOT_CACHE_DIR);
     await fs.writeJson(GODOT_CACHE_FILE, { godotPath }, { spaces: 2 });
   } catch {
-    // cache failures should not block execution
+    // 缓存失败不应该阻塞执行
   }
 }
 
+/**
+ * 提示用户输入 Godot 编辑器路径
+ * 
+ * @param {string} defaultPath - 默认路径
+ * @returns {Promise<string>} 用户输入的路径
+ */
 async function promptForGodotBinaryPath(defaultPath) {
   const { godotPath } = await inquirer.prompt([
     {
@@ -139,69 +201,142 @@ async function promptForGodotBinaryPath(defaultPath) {
   return godotPath.trim();
 }
 
+/**
+ * 解析并获取 Godot 编辑器可执行文件路径
+ * 
+ * 优先级：环境变量 > 缓存 > 默认路径
+ * 总是会询问用户，但将缓存值或默认值作为默认输入
+ * 
+ * @returns {Promise<string>} Godot 编辑器可执行文件路径
+ * @throws {Error} 当路径不可执行时抛出错误
+ */
 async function resolveGodotBinary() {
+  // 获取可能的默认值（优先级：环境变量 > 缓存 > 默认路径）
   const override = process.env.GODOT_EDITOR ? process.env.GODOT_EDITOR.trim() : '';
-  if (override && isExecutable(override)) {
-    return override;
-  }
-
   const cached = readCachedGodotPath();
-  if (cached && isExecutable(cached)) {
-    return cached;
-  }
-
-  if (isExecutable(DEFAULT_GODOT_BIN)) {
-    await writeCachedGodotPath(DEFAULT_GODOT_BIN);
-    return DEFAULT_GODOT_BIN;
-  }
-
-  const fallbackDefault = override || cached || DEFAULT_GODOT_BIN;
-  const godotPath = await promptForGodotBinaryPath(fallbackDefault);
-
+  
+  // 确定默认值
+  let defaultPath = override || cached || DEFAULT_GODOT_BIN;
+  
+  // 总是询问用户，但将缓存值或默认值作为默认输入
+  const godotPath = await promptForGodotBinaryPath(defaultPath);
+
+  // 验证路径是否可执行
   if (!isExecutable(godotPath)) {
     throw new Error(`Godot 二进制文件不可执行: ${godotPath}`);
   }
 
+  // 保存用户输入作为下次的默认值
   await writeCachedGodotPath(godotPath);
   return godotPath;
 }
 
+/**
+ * 执行 Godot 命令行命令
+ * 
+ * @param {string} godotBin - Godot 编辑器可执行文件路径
+ * @param {string[]} args - 命令参数
+ */
 async function runGodotCommand(godotBin, args) {
   await execa(godotBin, args, { stdio: 'inherit' });
 }
 
+/**
+ * 处理 Android 平台导出
+ * 
+ * Android 导出流程：
+ * 1. 使用 Godot 导出为 ZIP 包
+ * 2. 解压 ZIP 包到指定目录
+ * 3. 清理临时 ZIP 文件
+ * 
+ * @param {object} options - 导出选项
+ * @param {string} options.godotBin - Godot 编辑器路径
+ * @param {string} options.projectDir - Godot 项目目录
+ * @param {string} options.preset - 导出预设名称
+ * @param {string} options.targetBaseDir - 目标根目录
+ * @param {string} options.name - 导出文件名（不含扩展名）
+ */
 async function handleAndroidExport({ godotBin, projectDir, preset, targetBaseDir, name }) {
+  // Android 导出路径：targetBaseDir/android/app/src/main/assets/
   const assetsBaseDir = path.join(targetBaseDir, 'android', 'app', 'src', 'main', 'assets');
   await fs.ensureDir(assetsBaseDir);
 
+  // 使用 Godot 导出为 ZIP 包
   const zipPath = path.join(assetsBaseDir, `${name}.zip`);
   await runGodotCommand(godotBin, ['--headless', '--path', projectDir, '--export-pack', preset, zipPath]);
 
+  // 解压 ZIP 包到目标目录
   const targetDir = path.join(assetsBaseDir, name);
   await fs.remove(targetDir);
   await fs.ensureDir(targetDir);
 
   const zip = new AdmZip(zipPath);
   zip.extractAllTo(targetDir, true);
+  
+  // 清理临时 ZIP 文件
   await fs.remove(zipPath);
 }
 
+/**
+ * 处理 iOS 平台导出
+ * 
+ * iOS 导出流程：
+ * 1. 使用 Godot 直接导出为 PCK 文件
+ * 
+ * @param {object} options - 导出选项
+ * @param {string} options.godotBin - Godot 编辑器路径
+ * @param {string} options.projectDir - Godot 项目目录
+ * @param {string} options.preset - 导出预设名称
+ * @param {string} options.targetBaseDir - 目标根目录
+ * @param {string} options.name - 导出文件名（不含扩展名）
+ */
 async function handleIosExport({ godotBin, projectDir, preset, targetBaseDir, name }) {
+  // iOS 导出路径：targetBaseDir/ios/
   const assetsBaseDir = path.join(targetBaseDir, 'ios');
   await fs.ensureDir(assetsBaseDir);
+  
+  // 使用 Godot 直接导出为 PCK 文件
   const outputPath = path.join(assetsBaseDir, `${name}.pck`);
   await runGodotCommand(godotBin, ['--headless', '--path', projectDir, '--export-pack', preset, outputPath]);
 }
 
+/**
+ * 导出 Godot 项目
+ * 
+ * 主要流程：
+ * 1. 解析并获取 Godot 编辑器路径
+ * 2. 执行资源导入（执行两次以确保资源正确导入）
+ * 3. 根据平台执行相应的导出流程
+ * 
+ * @param {object} options - 导出选项
+ * @param {string} options.platform - 导出平台（'ios' 或 'android'）
+ * @param {string} options.projectDir - Godot 项目目录
+ * @param {string} options.preset - Godot 导出预设名称
+ * @param {string} options.targetBaseDir - 目标根目录
+ * @param {string} options.name - 导出文件名（不含扩展名）
+ * @throws {Error} 当平台不支持时抛出错误
+ * 
+ * @example
+ * await exportGodot({
+ *   platform: 'ios',
+ *   projectDir: './game',
+ *   preset: 'iOS',
+ *   targetBaseDir: './dist',
+ *   name: 'MyGame'
+ * });
+ */
 export async function exportGodot(options) {
+  // 解析并获取 Godot 编辑器路径
   const godotBin = await resolveGodotBinary();
   const { platform, projectDir, preset, targetBaseDir, name } = options;
 
   // 执行两次 import 以确保资源正确导入
+  // 某些情况下，第一次导入可能不完整，执行两次可以确保所有资源都被正确导入
   const importArgs = ['--headless', '--path', projectDir, '--import'];
   await runGodotCommand(godotBin, importArgs);
   await runGodotCommand(godotBin, importArgs);
 
+  // 根据平台执行相应的导出流程
   switch (platform) {
     case PLATFORMS.IOS:
       await handleIosExport({ godotBin, projectDir, preset, targetBaseDir, name });
@@ -214,11 +349,21 @@ export async function exportGodot(options) {
   }
 }
 
+/**
+ * 主函数（当文件作为 CLI 直接执行时）
+ * 
+ * 如果该文件被直接执行（而非作为模块导入），则运行主函数
+ */
 async function main() {
   const options = await promptGodotOptions();
   await exportGodot(options);
 }
 
+/**
+ * 检查当前文件是否作为 CLI 直接执行
+ * 
+ * @returns {boolean} 是否为 CLI 执行
+ */
 const isCliExecution = (() => {
   if (!process.argv[1]) {
     return false;
@@ -227,6 +372,7 @@ const isCliExecution = (() => {
   return cliUrl === import.meta.url;
 })();
 
+// 如果作为 CLI 直接执行，运行主函数
 if (isCliExecution) {
   main().catch((error) => {
     console.error(error.message || error);

package/src/index.mjs

@@ -1,11 +1,21 @@
 #!/usr/bin/env node
 
 /**
- * React Native 应用 CLI 工具
- * 用于管理多应用项目的开发、构建和部署
+ * 红糖云服应用 CLI 工具主入口
+ * 
+ * 功能：
+ * - 初始化新小程序项目
+ * - 小程序打包构建
+ * - 小程序真机调试
+ * - 清理临时文件
+ * 
+ * 支持项目类型：
+ * - 普通小程序项目（使用 webpack 构建）
+ * - Godot 游戏项目（使用 Godot 导出工具）
  *
  * @author CLI Team
  * @version 2.2.0
+ * @module index
  */
 
 import inquirer from 'inquirer';
@@ -27,12 +37,18 @@ import { incrementVersion, updateAppConfig } from './utils-functions.mjs';
 
 const projectPath = getProjectRoot();
 
-// 全局状态管理，用于优雅退出
+// ========== 全局状态管理 ==========
+// 用于优雅退出，避免重复退出操作
 let isExiting = false;
 let currentProcess = null;
 
 /**
- * 优雅退出处理
+ * 优雅退出处理函数
+ * 
+ * 当收到退出信号（如 Ctrl+C）时：
+ * 1. 尝试关闭正在运行的进程
+ * 2. 延迟退出，给清理操作一些时间
+ * 3. 如果已经在退出中，强制退出
  */
 function handleGracefulExit() {
   if (isExiting) {
@@ -64,14 +80,22 @@ function handleGracefulExit() {
   }, 100);
 }
 
-// 注册全局信号处理（使用 once 确保只注册一次）
+// ========== 注册全局信号处理 ==========
+// 使用 once 确保只注册一次
 // 注意：某些模块（如 debug.mjs）可能会移除这些监听器并添加自己的处理
-process.on('SIGINT', handleGracefulExit);
-process.on('SIGTERM', handleGracefulExit);
+process.on('SIGINT', handleGracefulExit);   // Ctrl+C
+process.on('SIGTERM', handleGracefulExit);  // 终止信号
 
 /**
  * 主启动函数
- * @param {string} action - 操作类型
+ * 
+ * 根据操作类型执行相应的功能：
+ * - MP_BUILD: 构建小程序包
+ * - MP_DEBUG: 启动真机调试服务器
+ * - CLEAN: 清理临时文件
+ * - QUIT: 退出程序
+ * 
+ * @param {string} action - 操作类型（ACTION_TYPES 中的值）
  */
 async function Start(action) {
   const actionNames = {
@@ -83,11 +107,13 @@ async function Start(action) {
 
   Logger.info(`当前操作: ${actionNames[action] || '未知操作'}`);
 
+  // ========== 退出操作 ==========
   if (action === ACTION_TYPES.QUIT) {
     Logger.info('再见!');
     return;
   }
 
+  // ========== 清理操作 ==========
   if (action === ACTION_TYPES.CLEAN) {
     const { cleanType } = await inquirer.prompt([
       {
@@ -134,17 +160,23 @@ async function Start(action) {
     return;
   }
 
-  // 显示应用选择界面
+  // ========== 构建/调试操作 ==========
   try {
+    // 读取应用配置
     const appConfigPath = path.join(projectPath, 'app.json');
     const appInfo = fse.readJsonSync(appConfigPath).htyf;
+    
+    // 检测是否为 Godot 项目（通过检查是否存在 project.godot 文件）
     const isGodot = fse.existsSync(path.join(projectPath, 'project.godot'));
-    Logger.info(`是否是Game项目: ${isGodot}`);
+    Logger.info(`项目类型: ${isGodot ? 'Godot 游戏项目' : '普通小程序项目'}`);
+    
     if (!appInfo) {
       Logger.error('应用配置不存在，请先在app.json中配置htyf');
       return;
     }
     
+    // ========== 版本处理 ==========
+    // 自动递增版本号作为默认值
     const version = appInfo?.version;
     const incrementedVersion = version ? incrementVersion(version) : '1.0.0';
     const { versionName } = await inquirer.prompt([
@@ -163,15 +195,18 @@ async function Start(action) {
     Logger.info(`用户选择:`);
     Logger.info(`版本名称: ${versionName}`);
 
+    // ========== 更新应用配置 ==========
+    // 合并用户输入的版本号到应用信息中
     const newAppInfo = lodash.merge({}, appInfo, {
       version: versionName,
     });
 
+    // 更新 app.json 文件
     if (!updateAppConfig(newAppInfo)) {
       return;
     }
 
-    // 显示操作信息
+    // ========== 显示应用信息 ==========
     console.log('\n' + boxen(
       chalk.cyan('应用信息') + '\n\n' +
       chalk.white('名称: ') + chalk.yellow(`${newAppInfo.name}`) + '\n' +
@@ -184,13 +219,16 @@ async function Start(action) {
       }
     ));
 
-    Logger.info('执行初始化...');
+    Logger.info('开始执行操作...');
 
+    // ========== 执行相应操作 ==========
     switch (action) {
       case ACTION_TYPES.MP_BUILD:
+        // 构建小程序包
         await mpBuildShell(newAppInfo, isGodot);
         break;
       case ACTION_TYPES.MP_DEBUG:
+        // 启动真机调试服务器
         await mpDebugShell(newAppInfo, isGodot);
         break;
       default:
@@ -203,7 +241,8 @@ async function Start(action) {
   }
 }
 
-// 主程序入口
+// ========== 主程序入口 ==========
+// 显示欢迎信息
 console.log('\n' + boxen(
   gradient.rainbow('🎯 红糖云服 应用 CLI 工具 v2.2.0') + '\n' +
   chalk.gray('用于管理多应用项目的开发、构建和部署') + '\n' +
@@ -217,7 +256,9 @@ console.log('\n' + boxen(
   }
 ));
 
-// 设置日志级别
+// ========== 命令行参数处理 ==========
+
+// 处理调试模式参数
 if (process.argv.includes('--debug')) {
   setLogLevel(LOG_LEVELS.DEBUG);
   Logger.debug('调试模式已启用');
@@ -226,7 +267,7 @@ if (process.argv.includes('--debug')) {
 // 记录启动日志
 Logger.writeToFile('CLI 工具启动', 'INFO');
 
-// 处理命令行清理参数
+// 处理清理参数（命令行直接清理，不进入交互界面）
 if (process.argv.includes('--clean')) {
   const cleanIndex = process.argv.indexOf('--clean');
   const cleanType = process.argv[cleanIndex + 1] || 'all';

package/src/webpack.config.mjs

@@ -60,13 +60,31 @@ export default (env = {}) => {
   if (appExposesOptions) {
     mpOptions = JSON.parse(decodeURI(appExposesOptions));
   }
+  
+  // 处理 exposes 路径，确保路径正确解析
+  // Module Federation 需要相对于 context 的路径，如果路径不以 ./ 开头，需要添加
+  if (mpOptions.exposes) {
+    const processedExposes = {};
+    for (const [key, value] of Object.entries(mpOptions.exposes)) {
+      // 如果路径不是绝对路径且不以 ./ 开头，添加 ./ 前缀
+      if (value && typeof value === 'string' && !path.isAbsolute(value) && !value.startsWith('./') && !value.startsWith('../')) {
+        processedExposes[key] = `./${value}`;
+      } else {
+        processedExposes[key] = value;
+      }
+    }
+    mpOptions.exposes = processedExposes;
+  }
+  
   console.log('\n');
-  console.log('=====mpOptions=====');
+  console.log('=====mpOptions (after processing)=====');
   console.log('\n');
   console.log('context:', projectRoot);
   console.log('\n');
   console.log('entry:', entry);
   console.log('\n');
+  console.log('exposes (processed):', JSON.stringify(mpOptions.exposes, null, 2));
+  console.log('\n');
   console.log(JSON.stringify(mpOptions, null, 2));
   console.log('\n');
   console.log('=====mpOptions=====');
@@ -77,6 +95,8 @@ export default (env = {}) => {
     entry,
     resolve: {
       ..._options,
+      // 确保扩展名解析正确
+      extensions: ['.tsx', '.ts', '.jsx', '.js', '.json', ...(_options.extensions || [])],
     },
     output: {
       // 默认输出路径，host模式下会被覆盖

package/src/ListImportsPlugin.mjs

@@ -1,105 +0,0 @@
-
-import path from 'path';
-import fse from 'fs-extra'
-import { fileURLToPath } from 'url'
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-const sharedPkg = fse.readJSONSync(path.join(__dirname, './shared-output.json'))
-
-function trimTemplateStrings(strings, ...values) {
-  let fullString = strings.reduce((acc, str, i) => acc + str + (values[i] || ''), '');
-  return fullString.replace(/^[ \t]+/gm, '');
-}
-
-export class HtyfModulesPlugin {
-  constructor(appConfig) {
-    this.config = appConfig;
-  }
-  apply(compiler) {
-    const config = this.config;
-    compiler.hooks.emit.tapAsync('AnalyzeThirdPartyModulesPlugin', (compilation, callback) => {
-      let thirdPartyModules = new Set();
-
-      compilation.modules.forEach(module => {
-        if (module.context && module.context.includes('node_modules')) {
-          let packageName = module.context.split('node_modules/')[1].split('/')[0];
-          if (packageName.startsWith('@')) {
-            packageName = module.context.split('node_modules/')[1].split('/').splice(0,2).join('/');
-          }
-          const ios_path = path.join(__dirname, '../node_modules/', packageName, 'ios');
-          const and_path = path.join(__dirname, '../node_modules/', packageName, 'android');
-          const isNative = fse.pathExistsSync(ios_path) || fse.pathExistsSync(and_path);
-          if (isNative) {
-            thirdPartyModules.add(packageName);
-          }
-        }
-      });
-      const nonsupport = []
-      thirdPartyModules = Array.from(thirdPartyModules);
-      for (const key in thirdPartyModules) {
-        const pkg = thirdPartyModules[key];
-        if (!sharedPkg[pkg]) {
-          if (
-            pkg !== 'expo-splash-screen' &&
-            pkg !== '@callstack/repack' &&
-            pkg !== 'react-native-iap'
-          ) {
-            nonsupport.push(pkg)
-          }
-        }
-      }
-      if (nonsupport.length) {
-        const msgArr = ['红糖云服暂不支持以上第三方native组件']
-        console.log(' ')
-        console.log('xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
-        console.log('xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
-        console.log(' ')
-        console.log('红糖云服暂不支持以下第三方native组件: ')
-        for (const key in nonsupport) {
-          const element = nonsupport[key];
-          const _msg = `${Number(key) + 1}. ${element}`;
-          console.log(_msg)
-          msgArr.push(_msg)
-        }
-        console.log(' ')
-        console.log('xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
-        console.log('xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
-        console.log(' ')
-        console.log(' ')
-        callback(msgArr.join(`\n`));
-        process.exit(1);
-      } else {
-        callback();
-      }
-    });
-    if (config.codeSigning) {
-      compiler.hooks.emit.tapAsync('WrapCodePlugin', (compilation, callback) => {
-        // 遍历所有编译过的资源文件
-        for (const filename in compilation.assets) {
-          if (compilation.assets.hasOwnProperty(filename)) {
-            // 获取文件内容
-            let source = compilation.assets[filename].source();
-
-            // 包裹代码
-            const wrappedSource = trimTemplateStrings`
-            try {
-              ${source}
-            } catch (error) {
-              const that = globalThis || global || self || window;
-              that.__htyf_error_callback__ && that.__htyf_error_callback__(error, that)
-              console.error(error)
-            }
-            `;
-
-            // 更新文件内容
-            compilation.assets[filename] = {
-              source: () => wrappedSource,
-              size: () => wrappedSource.length
-            };
-          }
-        }
-        callback();
-      });
-    }
-  }
-}