@playcraft/devkit 1.0.27 → 1.0.28

package/cli/commands/build.js

@@ -10,6 +10,7 @@ const { runThemeValidation, restoreSchema } = require('../../core/utils/validate
 const { runPreBuildChecks } = require('../../core/validators/pre-build-checker.js');
 const { FontInjectionWebpackPlugin } = require('../../core/plugins/FontInjectionWebpackPlugin.js');
 const { SocialMediaInjectorPlugin } = require('../../core/plugins/SocialMediaInjectorPlugin.js');
+const { getPlaycraftOrientationSuffix } = require('../../core/utils/getPlaycraftOrientationSuffix.js');
 const { options } = require('../../core/options.js');
 
 /**
@@ -157,30 +158,80 @@ function continueWithBuild() {
     }
   }
 
-  // 注入字体插件（build 模式 base64 内联）
-  const fontPlugin = themeName
-    ? new FontInjectionWebpackPlugin({ projectRoot, themeName, themeConfig })
-    : null;
-
-  // social_media 渠道：注入 OG / Twitter meta 标签，让 Facebook / LinkedIn
-  // 等抓取预览时拿到正确的标题/描述/图片。无 shareMeta 时空跑，不影响构建
-  const socialMediaPlugin = (themeName && adNetwork === 'social_media')
-    ? new SocialMediaInjectorPlugin({ projectRoot, themeName, themeConfig })
-    : null;
-
-  // 执行构建，无论成功或失败都恢复 schema
-  runBuild(undefined, undefined, undefined, {
-    plugins: [
-      ...(fontPlugin ? [fontPlugin] : []),
-      ...(socialMediaPlugin ? [socialMediaPlugin] : []),
-    ],
-  })
-    .then(() => {
+  // ============================================================
+  // 📌 横竖屏方向多版本构建
+  // ============================================================
+  // playcraftOrientationChannel 中指定的渠道，需要按 playcraftOrientation
+  // 列出的每个方向版本分别打一个包（渠道_L / 渠道_P / 渠道，即 both 无后缀）；
+  // 不在列表中的渠道始终只按 both（自适应）打一个包。
+  const orientationChannels = options['playcraftOrientationChannel'] || [];
+  const orientationVersions =
+    Array.isArray(options['playcraftOrientation']) && options['playcraftOrientation'].length > 0
+      ? options['playcraftOrientation']
+      : ['both'];
+  const buildOrientations = orientationChannels.includes(adNetwork) ? orientationVersions : ['both'];
+
+  /**
+   * 构建单个方向版本
+   */
+  async function buildOneOrientation(orientationValue) {
+    const suffix = getPlaycraftOrientationSuffix(orientationValue);
+    if (buildOrientations.length > 1) {
+      console.log(`\n📱 开始构建方向版本: ${orientationValue}${suffix ? ` (后缀: ${suffix})` : ''}`);
+    }
+
+    // 注入字体插件（build 模式 base64 内联）
+    const fontPlugin = themeName
+      ? new FontInjectionWebpackPlugin({ projectRoot, themeName, themeConfig })
+      : null;
+
+    // social_media 渠道：注入 OG / Twitter meta 标签，让 Facebook / LinkedIn
+    // 等抓取预览时拿到正确的标题/描述/图片。无 shareMeta 时空跑，不影响构建
+    const socialMediaPlugin = (themeName && adNetwork === 'social_media')
+      ? new SocialMediaInjectorPlugin({ projectRoot, themeName, themeConfig })
+      : null;
+
+    await runBuild(
+      undefined,
+      {
+        playcraftOrientationValue: orientationValue,
+        filename: suffix ? `${options.filename}${suffix}` : options.filename
+      },
+      undefined,
+      {
+        plugins: [
+          ...(fontPlugin ? [fontPlugin] : []),
+          ...(socialMediaPlugin ? [socialMediaPlugin] : []),
+        ],
+      }
+    );
+  }
+
+  (async () => {
+    try {
+      // 注意：方向版本之间故意串行执行（不用 Promise.all 并发）。
+      // 原因：obfuscateLevel=4 等重度混淆/压缩下单次 webpack 编译本身就
+      // 会占用数 GB 内存；而该 build.js 进程本身通常已是 batch-build.js
+      // 渠道级并发中的一个子进程（多个渠道同时在跑）。若在这里再叠加同
+      // 进程内的多方向并发（多个 webpack compiler 共享同一份 V8 堆），
+      // 内存需求会成倍叠加，实测会导致 "JavaScript heap out of memory"
+      // 崩溃。因此并发只在渠道层（各自独立进程、独立堆）进行，方向版本
+      // 层始终串行，以保证稳定性。
+      for (const orientationValue of buildOrientations) {
+        await buildOneOrientation(orientationValue);
+      }
+
       if (schemaPathToRestore) restoreSchema(schemaPathToRestore);
-    })
-    .catch((err) => {
+
+      // 主动退出进程，避免 TerserPlugin/webpack-obfuscator 等可能残留的
+      // worker 进程句柄（jest-worker 子进程 IPC 通道等）迟迟不释放，
+      // 导致本次 build 子进程（乃至上层 batch-build 的 spawn 等待）
+      // 迟迟无法结束。此时构建已全部完成，不再有需要等待的异步操作。
+      process.exit(0);
+    } catch (err) {
       if (schemaPathToRestore) restoreSchema(schemaPathToRestore);
       console.error(err);
       process.exit(1);
-    });
+    }
+  })();
 }

package/core/batch-build.js

@@ -12,16 +12,83 @@
  * 4. 支持灵活的配置系统
  */
 
-const { execSync, exec } = require('child_process');
+const { execSync, spawn } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { promisify } = require('util');
 const { fetchTemporaryCredentials, createCOSClient, uploadDirectoryToCOS, uploadFileToCOS, purgeCDNCache } = require('./cos-uploader');
 const { runThemeValidation, restoreSchema } = require('./utils/validateThemeData');
 const { runPreBuildChecks } = require('./validators/pre-build-checker.js');
+const { getPlaycraftOrientationSuffix } = require('./utils/getPlaycraftOrientationSuffix.js');
 
-const execAsync = promisify(exec);
+/**
+ * 执行构建命令，实时把 stdout/stderr 落盘到日志文件，而不是像 exec()
+ * 那样把全部输出攒在内存里的一个 buffer 中。
+ *
+ * 背景：exec() 的 maxBuffer 是硬性内存上限（原来设为 10MB）。当某个渠道
+ * 需要连续构建多个方向版本（playcraftOrientationChannel）时，日志量会
+ * 成倍增加，很容易超过该上限触发 "stderr maxBuffer length exceeded" 而
+ * 直接杀掉子进程。改用 spawn 边收边写文件后，日志大小不再受内存限制；
+ * 内存中只保留末尾一小段用于失败时快速定位问题，完整日志可在日志文件中查看。
+ *
+ * @param {string} command - 要执行的命令（通过 shell 解析，支持带引号的参数）
+ * @param {object} options - spawn 选项（cwd/env 等）
+ * @param {string} logPath - 日志文件落盘路径
+ * @returns {Promise<{logPath: string}>}
+ */
+function execWithLoggedOutput(command, options, logPath) {
+  return new Promise((resolve, reject) => {
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    const logStream = fs.createWriteStream(logPath, { flags: 'w' });
+
+    const TAIL_LIMIT = 8000; // 失败时用于在错误信息中展示的日志末尾字符数
+    let tail = '';
+    const appendTail = (chunk) => {
+      tail += chunk;
+      if (tail.length > TAIL_LIMIT) {
+        tail = tail.slice(tail.length - TAIL_LIMIT);
+      }
+    };
+
+    let child;
+    try {
+      child = spawn(command, { ...options, shell: true });
+    } catch (err) {
+      logStream.end();
+      reject(err);
+      return;
+    }
+
+    child.stdout && child.stdout.on('data', (chunk) => {
+      logStream.write(chunk);
+      appendTail(chunk.toString());
+    });
+    child.stderr && child.stderr.on('data', (chunk) => {
+      logStream.write(chunk);
+      appendTail(chunk.toString());
+    });
+
+    child.on('error', (err) => {
+      logStream.end();
+      reject(err);
+    });
+
+    child.on('close', (code) => {
+      logStream.end(() => {
+        if (code === 0) {
+          resolve({ logPath });
+        } else {
+          const err = new Error(
+            `子进程退出码 ${code}\n---- 日志末尾 ----\n${tail}\n---- 完整日志见: ${logPath} ----`
+          );
+          err.logPath = logPath;
+          err.exitCode = code;
+          reject(err);
+        }
+      });
+    });
+  });
+}
 
 /**
  * 更新 preview.json 文件
@@ -359,14 +426,64 @@ function copyDirRecursive(src, dest) {
   }
 }
 
+/**
+ * 根据 playcraftOrientationChannel / playcraftOrientation 配置，把渠道列表
+ * 展开为「渠道构建任务」列表：需要多方向版本的渠道会被拆分成多个独立任务
+ * （对应 渠道_L / 渠道_P / 渠道 三个方向），每个任务各自对应一次独立的
+ * 子进程构建。
+ *
+ * 背景：此前多方向版本是在单个子进程（cli/commands/build.js）内部循环
+ * 串行构建的，obfuscateLevel=4 等重度混淆下单次编译本身就占用较大内存/
+ * 日志量，3 个方向串行叠加很容易撑爆内存或撑爆日志 buffer。改为在这里
+ * 提前拆分任务后，多方向构建就和普通的多渠道构建一样，交给已有的
+ * `buildChannelsInParallel` 并发调度（各任务独立进程、独立堆、独立日志
+ * 文件），从而把「单进程内串行」变成「渠道层面的多进程并发」。
+ *
+ * @param {string[]} channels - 原始渠道列表（已包含 'preview'）
+ * @param {object} config - 批量构建配置
+ * @returns {{channel: string, orientation: ('both'|'landscape'|'portrait'|null)}[]}
+ */
+function buildChannelTasks(channels, config) {
+  const orientationChannels = config.playcraftOrientationChannel || [];
+  const orientationVersions =
+    Array.isArray(config.playcraftOrientation) && config.playcraftOrientation.length > 0
+      ? config.playcraftOrientation
+      : ['both'];
+
+  const tasks = [];
+  for (const channel of channels) {
+    // preview 渠道用于收集预览文件，不参与多方向拆分
+    if (channel !== 'preview' && orientationChannels.includes(channel)) {
+      for (const orientation of orientationVersions) {
+        tasks.push({ channel, orientation });
+      }
+    } else {
+      tasks.push({ channel, orientation: null });
+    }
+  }
+  return tasks;
+}
+
+/**
+ * 生成任务展示标签，用于日志中区分同一渠道下的不同方向任务，如 google(landscape) → google_L
+ */
+function getTaskLabel(channel, orientation) {
+  if (!orientation) return channel;
+  const suffix = getPlaycraftOrientationSuffix(orientation);
+  return suffix ? `${channel}${suffix}` : channel;
+}
+
 /**
  * 构建单个渠道（使用独立临时目录）
+ * @param {('both'|'landscape'|'portrait'|null)} [orientation] - 指定要强制构建的单一方向版本；
+ *   为 null/undefined 时不干预，由渠道自身默认逻辑决定（通常即 'both'）
  */
-async function buildChannel(config, themeName, channel, outputDir, projectRoot, isChannelFold2Zip) {
+async function buildChannel(config, themeName, channel, outputDir, projectRoot, isChannelFold2Zip, orientation) {
   const taskId = generateTaskId();
   const tempDir = createTempDir(config, projectRoot, taskId);
+  const taskLabel = getTaskLabel(channel, orientation);
   
-  log(`开始构建: 主题=${themeName}, 渠道=${channel}, 任务ID=${taskId.substr(0, 8)}...`);
+  log(`开始构建: 主题=${themeName}, 渠道=${taskLabel}, 任务ID=${taskId.substr(0, 8)}...`);
   
   try {
     // 生成文件名
@@ -380,7 +497,7 @@ async function buildChannel(config, themeName, channel, outputDir, projectRoot,
     // 注意：
     // 1. 命令行参数使用 --out-dir (连字符格式)
     // 2. 通过环境变量 PLAYABLE_FILENAME 传递文件名，避免并发时修改 build.json 导致竞态条件
-    // 3. 使用 execAsync 实现真正的并发构建
+    // 3. 使用 spawn + 落盘日志实现真正的并发构建（避免 exec 的内存 buffer 上限）
     // 4. 通过命令行参数传递商店链接（如果配置中有定义）
     
     // 构建命令行参数
@@ -398,23 +515,51 @@ async function buildChannel(config, themeName, channel, outputDir, projectRoot,
     if (isChannelFold2Zip) {
       buildArgs.push('--is-channel-fold2zip');
     }
+
+    // 指定单一方向版本：显式传入仅含该方向的 --playcraft-orientation，
+    // 并把当前渠道加入 --playcraft-orientation-channel，使子进程内
+    // （cli/commands/build.js）的方向循环只会执行这一个方向，从而把
+    // 「单进程内串行构建多个方向」变成「渠道层面的多进程并发构建」。
+    if (orientation) {
+      buildArgs.push(`--playcraft-orientation ${orientation}`);
+      buildArgs.push(`--playcraft-orientation-channel ${channel}`);
+    }
     
-    await execAsync(`npm run build -- ${buildArgs.join(' ')}`, {
-      cwd: projectRoot,
-      env: {
-        ...process.env,
-        PLAYABLE_BUILD_TASK_ID: taskId,
-        PLAYABLE_FILENAME: fileName,  // 通过环境变量传递文件名
-        PLAYABLE_BATCH_MODE: '1'     // 标识批量构建模式，子进程跳过 runThemeValidation（主进程已处理）
-      },
-      // 不使用 stdio: 'inherit' 以支持并发，而是捕获输出
-      maxBuffer: 10 * 1024 * 1024 // 10MB buffer
-    });
+    const buildLogPath = path.join(
+      projectRoot,
+      '.playable-build-logs',
+      `${themeName}_${taskLabel}_${taskId.substr(0, 8)}.log`
+    );
+
+    try {
+      await execWithLoggedOutput(`npm run build -- ${buildArgs.join(' ')}`, {
+        cwd: projectRoot,
+        env: {
+          ...process.env,
+          // 兜底：即使 webpack compiler 已正确 close()，重度混淆(obfuscateLevel=4)
+          // 下多方向串行构建仍可能瞬时占用较大堆内存，此处适当调高上限做防御
+          // （不覆盖用户已自行设置的 NODE_OPTIONS）
+          NODE_OPTIONS: process.env.NODE_OPTIONS || '--max-old-space-size=8192',
+          PLAYABLE_BUILD_TASK_ID: taskId,
+          PLAYABLE_FILENAME: fileName,  // 通过环境变量传递文件名
+          PLAYABLE_BATCH_MODE: '1'     // 标识批量构建模式，子进程跳过 runThemeValidation（主进程已处理）
+        }
+      }, buildLogPath);
+
+      // 构建成功后日志已无需保留，删除避免日志文件堆积
+      fs.rmSync(buildLogPath, { force: true });
+    } catch (buildError) {
+      // 失败时保留日志文件，方便排查（不在这里删除）
+      throw buildError;
+    }
     
     // 复制 tempDir 所有文件到目标目录
-    // 第二级目录名使用 "主题名_渠道名"，避免不同主题下同名渠道目录/文件混淆
+    // 第二级目录名使用 "主题名_渠道名[_L|_P]"，避免不同主题下同名渠道目录/文件混淆；
+    // 若该渠道被 playcraftOrientationChannel 拆分为多方向任务，还需带上方向后缀，
+    // 否则 landscape/portrait/both 三个并发任务会把产物混进同一个文件夹
     function copyTempFiles(outputDir, themeName, channel) {
-      const channelDirName = `${themeName}_${channel}`;
+      const orientationSuffix = orientation ? getPlaycraftOrientationSuffix(orientation) : '';
+      const channelDirName = `${themeName}_${channel}${orientationSuffix}`;
       const targetDir = path.join(outputDir, themeName, channelDirName);
       if (!fs.existsSync(targetDir)) {
         fs.mkdirSync(targetDir, { recursive: true });
@@ -432,27 +577,31 @@ async function buildChannel(config, themeName, channel, outputDir, projectRoot,
         }
       });
       
-      log(`✓ 构建成功: ${themeName}/${channel} → ${themeName}/${channelDirName}`, 'success');
+      log(`✓ 构建成功: ${themeName}/${taskLabel} → ${themeName}/${channelDirName}`, 'success');
     }
     
     // 移动构建产物到目标目录
     if (fs.existsSync(tempDir)) {
       if (isChannelFold2Zip && channel !== 'preview') {
-        // isChannelFold2Zip 模式：只移动 渠道名.zip 到 outputDir/themeName/主题名_渠道名.zip
-        const zipFileName = `${channel}.zip`;
-        const destZipFileName = `${themeName}_${channel}.zip`;
-        const srcZipPath = path.join(tempDir, zipFileName);
+        // isChannelFold2Zip 模式：移动 渠道名[.zip|_L.zip|_P.zip] 到 outputDir/themeName/主题名_渠道名[_L|_P].zip
+        // 注：若该渠道被配置为多方向版本构建（playcraftOrientationChannel），tempDir 内
+        // 会同时存在 channel.zip / channel_L.zip / channel_P.zip 中的一个或多个，需要全部匹配并逐个复制
+        const zipRegex = new RegExp(`^${channel}(_L|_P)?\\.zip$`);
         const themeDir = path.join(outputDir, themeName);
-        const destZipPath = path.join(themeDir, destZipFileName);
-        
-        if (fs.existsSync(srcZipPath)) {
+        const matchedZipFiles = fs.readdirSync(tempDir).filter((file) => zipRegex.test(file));
+
+        if (matchedZipFiles.length > 0) {
           if (!fs.existsSync(themeDir)) {
             fs.mkdirSync(themeDir, { recursive: true });
           }
-          fs.copyFileSync(srcZipPath, destZipPath);
-          log(`✓ 构建成功: ${themeName}/${channel} → ${themeName}/${destZipFileName}`, 'success');
+          matchedZipFiles.forEach((zipFileName) => {
+            const suffix = zipFileName.match(zipRegex)[1] || '';
+            const destZipFileName = `${themeName}_${channel}${suffix}.zip`;
+            fs.copyFileSync(path.join(tempDir, zipFileName), path.join(themeDir, destZipFileName));
+            log(`✓ 构建成功: ${themeName}/${channel}${suffix} → ${themeName}/${destZipFileName}`, 'success');
+          });
         } else {
-          log(`⚠️ 未找到 zip 文件: ${srcZipPath}，回退到普通文件移动`, 'warn');
+          log(`⚠️ 未找到 zip 文件: ${channel}*.zip，回退到普通文件移动`, 'warn');
           // 回退：移动所有文件到 outputDir/themeName/主题名_渠道名/
           copyTempFiles(outputDir, themeName, channel);
         }
@@ -467,9 +616,9 @@ async function buildChannel(config, themeName, channel, outputDir, projectRoot,
       cleanTempDir(tempDir);
     }
     
-    return { success: true, theme: themeName, channel };
+    return { success: true, theme: themeName, channel, orientation };
   } catch (error) {
-    log(`构建失败: ${themeName}/${channel} - ${error.message}`, 'error');
+    log(`构建失败: ${themeName}/${taskLabel} - ${error.message}`, 'error');
     
     // 清理临时目录
     if (config.build.cleanTemp) {
@@ -480,22 +629,22 @@ async function buildChannel(config, themeName, channel, outputDir, projectRoot,
       throw error;
     }
     
-    return { success: false, theme: themeName, channel, error: error.message };
+    return { success: false, theme: themeName, channel, orientation, error: error.message };
   }
 }
 
 /**
- * 并发构建多个渠道
+ * 并发构建多个渠道任务（一个任务 = 一个渠道的一个方向版本，preview 渠道无方向拆分）
  */
-async function buildChannelsInParallel(config, themeName, channels, outputDir, projectRoot, isChannelFold2Zip) {
+async function buildChannelsInParallel(config, themeName, tasks, outputDir, projectRoot, isChannelFold2Zip) {
   const maxParallel = config.build.parallel || 3;
   const results = [];
   
   // 分批并发构建
-  for (let i = 0; i < channels.length; i += maxParallel) {
-    const batch = channels.slice(i, i + maxParallel);
-    const batchPromises = batch.map(channel => 
-      buildChannel(config, themeName, channel, outputDir, projectRoot, isChannelFold2Zip)
+  for (let i = 0; i < tasks.length; i += maxParallel) {
+    const batch = tasks.slice(i, i + maxParallel);
+    const batchPromises = batch.map(task => 
+      buildChannel(config, themeName, task.channel, outputDir, projectRoot, isChannelFold2Zip, task.orientation)
     );
     
     const batchResults = await Promise.allSettled(batchPromises);
@@ -507,7 +656,8 @@ async function buildChannelsInParallel(config, themeName, channels, outputDir, p
         results.push({
           success: false,
           theme: themeName,
-          channel: batch[index],
+          channel: batch[index].channel,
+          orientation: batch[index].orientation,
           error: result.reason?.message || '未知错误'
         });
       }
@@ -818,9 +968,13 @@ function mergeConfig(defaultConfig, userConfig) {
 
 /**
  * 打印配置摘要
+ * @param {object} config
+ * @param {string[]} themes
+ * @param {string[]} channels - 原始渠道列表（未展开方向）
+ * @param {{channel:string, orientation:(string|null)}[]} tasks - 展开方向后的实际构建任务列表
  */
-function printSummary(config, themes, channels) {
-  const totalBuilds = themes.length * channels.length;
+function printSummary(config, themes, channels, tasks) {
+  const totalBuilds = themes.length * tasks.length;
   const cpuCount = os.cpus().length;
   const cpuModel = os.cpus()[0]?.model || 'Unknown';
   
@@ -829,6 +983,9 @@ function printSummary(config, themes, channels) {
   log(`项目: ${config.title}`);
   log(`主题数: ${themes.length}`);
   log(`渠道数: ${channels.length}`);
+  if (tasks.length !== channels.length) {
+    log(`构建任务数(展开多方向后): ${tasks.length}`);
+  }
   log(`总构建数: ${totalBuilds}`);
   log(`CPU: ${cpuCount} 核心 (${cpuModel.substring(0, 40)}${cpuModel.length > 40 ? '...' : ''})`);
   log(`并发数: ${config.build.parallel} (自动优化)`);
@@ -838,6 +995,10 @@ function printSummary(config, themes, channels) {
     log(`主题列表: ${themes.join(', ')}`, 'debug');
   }
   log(`渠道列表: ${channels.join(', ')}`, 'debug');
+  if (tasks.length !== channels.length) {
+    const taskLabels = tasks.map(t => getTaskLabel(t.channel, t.orientation));
+    log(`已按 playcraftOrientationChannel 展开为独立并发任务: ${taskLabels.join(', ')}`, 'info');
+  }
   log('');
 }
 
@@ -888,6 +1049,11 @@ async function buildBatch() {
       log('已添加 preview 渠道', 'info');
     }
     
+    // 根据 playcraftOrientationChannel / playcraftOrientation 配置，把需要
+    // 多方向版本的渠道拆分为独立的构建任务（渠道_L / 渠道_P / 渠道），
+    // 后续统一交给渠道级并发调度，每个方向各自独立进程构建。
+    const tasks = buildChannelTasks(channels, config);
+    
     // ============================================================
     // 📌 编译前检查（埋点验证、主题名称检查等）- 仅在主进程执行一次
     // ============================================================
@@ -915,7 +1081,7 @@ async function buildBatch() {
     }
     
     // 打印摘要
-    printSummary(config, themes, channels);
+    printSummary(config, themes, channels, tasks);
     
     // 备份入口文件（如果启用主题切换）
     if (config.themes.enabled) {
@@ -955,20 +1121,20 @@ async function buildBatch() {
         if (!config.build.continueOnError) {
           throw new Error(`Theme data validation failed for "${theme}"`);
         }
-        // Record failures for all channels of this theme and skip building
-        channels.forEach(channel => {
-          allResults.push({ success: false, theme, channel, error: 'Theme data validation failed' });
+        // Record failures for all tasks of this theme and skip building
+        tasks.forEach(({ channel, orientation }) => {
+          allResults.push({ success: false, theme, channel, orientation, error: 'Theme data validation failed' });
         });
         continue;
       }
       
-      // 并发构建该主题的所有渠道
+      // 并发构建该主题的所有渠道任务（多方向渠道已展开为独立任务）
       let themeResults;
       try {
         themeResults = await buildChannelsInParallel(
           config,
           theme,
-          channels,
+          tasks,
           outputDir,
           projectRoot,
           isChannelFold2Zip
@@ -1039,7 +1205,7 @@ async function buildBatch() {
       
       // 打印进度
       const completedBuilds = allResults.length;
-      const totalBuilds = themes.length * channels.length;
+      const totalBuilds = themes.length * tasks.length;
       const progress = Math.round(completedBuilds / totalBuilds * 100);
       log(`进度: ${completedBuilds}/${totalBuilds} (${progress}%)`, 'success');
     }
@@ -1090,8 +1256,8 @@ async function buildBatch() {
     
     if (failedBuilds.length > 0) {
       log(`✗ 失败构建: ${failedBuilds.length}`, 'warn');
-      failedBuilds.forEach(({ theme, channel, error }) => {
-        log(`  - ${theme}/${channel}: ${error}`, 'error');
+      failedBuilds.forEach(({ theme, channel, orientation, error }) => {
+        log(`  - ${theme}/${getTaskLabel(channel, orientation)}: ${error}`, 'error');
       });
     }
     
@@ -1126,6 +1292,10 @@ async function buildBatch() {
     
     log('========================================');
     
+    // 主动退出进程：COS SDK 的 https keep-alive 连接、子进程遗留的 IPC 句柄
+    // 等都可能让事件循环迟迟无法自然清空，导致命令执行完毕后终端长时间不返回。
+    // 此处所有任务已全部完成，无需再等待任何异步操作，直接退出即可。
+    process.exit(0);
   } catch (error) {
     log(`严重错误: ${error.message}`, 'error');
     console.error(error);

package/core/index.d.ts

@@ -46,8 +46,8 @@ export interface DefinesOptions {
   BUILD_HASH: string;
   /** Current language code */
   LANGUAGE: string;
-  /** Current orientation identifier */
-  ORIENTATION: 'both' | 'portrait' | 'landscape' | 'square';
+  /** Current playcraft orientation identifier (window.playcraftOrientation / PLAYCRAFT_ORIENTATION define) */
+  PLAYCRAFT_ORIENTATION: 'both' | 'landscape' | 'portrait';
 }
 
 /** CLI configuration options */
@@ -110,8 +110,12 @@ export interface CLIOptions {
   version: string;
   /** Language code for localization */
   language: 'auto' | 'en' | 'es' | 'zh' | 'hi' | 'ar' | 'fr' | 'de' | 'ja' | 'pt';
-  /** Orientation identifier */
-  orientation: 'both' | 'portrait' | 'landscape' | 'square';
+  /** 当前要打包的横竖屏方向版本列表（builds.config.js 专属），默认 ['both'] */
+  playcraftOrientation: ('both' | 'landscape' | 'portrait')[];
+  /** 哪些渠道需要按 playcraftOrientation 分别打出多个方向版本的包（builds.config.js 专属），默认 [] */
+  playcraftOrientationChannel: string[];
+  /** 当前单次构建实际使用的横竖屏方向版本值（内部循环时按需注入，非 CLI 参数），默认 'both' */
+  playcraftOrientationValue?: 'both' | 'landscape' | 'portrait';
   /** Google Play Store URL for the app */
   googlePlayUrl: string;
   /** App Store URL for the app */

package/core/options.js

@@ -2,7 +2,7 @@ const {
   parseArgvOptions,
   allowedAdProtocols,
   allowedAdNetworks,
-  allowedOrientations,
+  allowedPlaycraftOrientations,
   allowedLanguages
 } = require('./utils/parseArgvOptions');
 const path = require('path');
@@ -137,15 +137,31 @@ const possibleOptions = [
     }
   },
   {
-    name: 'orientation',
-    defaultValue: 'both',
+    name: 'playcraft-orientation',
+    alias: 'playcraftOrientation',
+    defaultValue: ['both'],
     hasValue: true,
-    description: 'Specifies the ad orientation used in ORIENTATION define and some network specific configurations',
+    description:
+      '当前要打包的横竖屏方向版本列表，可指定多个（逗号分隔），取值：landscape/portrait/both。用于 PLAYCRAFT_ORIENTATION define 及 window.playcraftOrientation 运行时变量',
     parser: function (rawValue) {
-      if (!allowedOrientations.includes(rawValue)) {
-        throw new Error(`--orientation should have one of the value: ${allowedOrientations.join(', ')}`);
+      const values = rawValue.split(',').map((v) => v.trim()).filter(Boolean);
+      for (const value of values) {
+        if (!allowedPlaycraftOrientations.includes(value)) {
+          throw new Error(`--playcraft-orientation should have one of the value: ${allowedPlaycraftOrientations.join(', ')}`);
+        }
       }
-      return rawValue;
+      return values;
+    }
+  },
+  {
+    name: 'playcraft-orientation-channel',
+    alias: 'playcraftOrientationChannel',
+    defaultValue: [],
+    hasValue: true,
+    description:
+      '哪些渠道需要按 playcraftOrientation 分别打出多个方向版本的包（逗号分隔的渠道名列表）。不在此列表中的渠道始终按 both（自适应）单一版本打包',
+    parser: function (rawValue) {
+      return rawValue.split(',').map((v) => v.trim()).filter(Boolean);
     }
   },
   {

package/core/plugins/ExitAPIInjectorPlugin.js

@@ -10,10 +10,10 @@ const HtmlWebpackPlugin = require('html-webpack-plugin');
  */
 class ExitAPIInjectorPlugin {
   /**
-   * @param {ORIENTATION} orientation - device orientation
+   * @param {'both'|'landscape'|'portrait'} orientation - 当前构建的横竖屏方向版本，默认 'both'
    */
   constructor(orientation) {
-    this.orientation = orientation;
+    this.orientation = orientation || 'both';
   }
 
   apply(compiler) {
@@ -32,8 +32,7 @@ class ExitAPIInjectorPlugin {
         let width = 320;
         let height = 480;
 
-        if (this.orientation === 'square') width = 480;
-        else if (this.orientation === 'landscape') {
+        if (this.orientation === 'landscape') {
           width = 480;
           height = 320;
         }
@@ -51,7 +50,7 @@ class ExitAPIInjectorPlugin {
           meta: { plugin: 'html-webpack-plugin' },
           attributes: {
             name: 'ad.orientation',
-            content: this.orientation === 'both' || this.orientation === 'square' ? 'portrait,landscape' : this.orientation
+            content: this.orientation === 'both' ? 'portrait,landscape' : this.orientation
           }
         });
 

package/core/plugins/PlaycraftOrientationInjectorPlugin.js

@@ -0,0 +1,33 @@
+const HtmlWebpackPlugin = require('html-webpack-plugin');
+
+/**
+ * 在 HTML <head> 最前面注入 window.playcraftOrientation 全局变量，
+ * 标识当前构建产物对应的横竖屏方向版本，供游戏/主题代码在运行时读取判断。
+ * @implements {import('webpack').WebpackPluginInstance}
+ */
+class PlaycraftOrientationInjectorPlugin {
+  /**
+   * @param {'both'|'landscape'|'portrait'} orientation - 当前构建的方向版本，默认 'both'
+   */
+  constructor(orientation) {
+    this.orientation = orientation || 'both';
+  }
+
+  apply(compiler) {
+    compiler.hooks.compilation.tap('PlaycraftOrientationInjectorPlugin', (compilation) => {
+      HtmlWebpackPlugin.getHooks(compilation).alterAssetTagGroups.tapAsync('PlaycraftOrientationInjectorPlugin', (data, callback) => {
+        data.headTags.splice(0, 0, {
+          tagName: 'script',
+          voidTag: false,
+          meta: { plugin: 'html-inline-script-webpack-plugin' },
+          attributes: { type: 'text/javascript' },
+          innerHTML: `window.playcraftOrientation=${JSON.stringify(this.orientation)};`
+        });
+
+        callback(null, data);
+      });
+    });
+  }
+}
+
+exports.PlaycraftOrientationInjectorPlugin = PlaycraftOrientationInjectorPlugin;

package/core/utils/buildDefines.js

@@ -2,24 +2,26 @@ const { options } = require('../options');
 
 /**
  * Build's default defines list for dev & prod builds
+ * @param {import('../index').CLIOptions} [customOptions] - 合并后的当前构建选项（用于读取会随单次构建变化的字段，如 playcraftOrientationValue）；未提供时回退到全局 options
  */
-exports.buildDefines = function buildDefines() {
+exports.buildDefines = function buildDefines(customOptions) {
+  const opts = customOptions || options;
   const defines = {
-    __DEV__: JSON.stringify(options['dev'] === undefined ? false : options['dev']),
-    GOOGLE_PLAY_URL: JSON.stringify(options.googlePlayUrl),
-    APP_STORE_URL: JSON.stringify(options.appStoreUrl),
-    AD_NETWORK: JSON.stringify(options['network']),
-    AD_PROTOCOL: JSON.stringify(options['protocol']),
-    APP: JSON.stringify(options.app),
-    NAME: JSON.stringify(options.name),
-    VERSION: JSON.stringify(options.version),
+    __DEV__: JSON.stringify(opts['dev'] === undefined ? false : opts['dev']),
+    GOOGLE_PLAY_URL: JSON.stringify(opts.googlePlayUrl),
+    APP_STORE_URL: JSON.stringify(opts.appStoreUrl),
+    AD_NETWORK: JSON.stringify(opts['network']),
+    AD_PROTOCOL: JSON.stringify(opts['protocol']),
+    APP: JSON.stringify(opts.app),
+    NAME: JSON.stringify(opts.name),
+    VERSION: JSON.stringify(opts.version),
     BUILD_HASH: JSON.stringify((+new Date()).toString(36)),
-    LANGUAGE: JSON.stringify(options.language),
-    ORIENTATION: JSON.stringify(options.orientation)
+    LANGUAGE: JSON.stringify(opts.language),
+    PLAYCRAFT_ORIENTATION: JSON.stringify(opts.playcraftOrientationValue || 'both')
   };
 
   /** @type {AD_NETWORK} */
-  let adNetworkDefine = options['network'];
+  let adNetworkDefine = opts['network'];
 
   if (adNetworkDefine === 'pangle') adNetworkDefine = 'tiktok';
   if (adNetworkDefine === 'mytarget' || adNetworkDefine === 'moloco') adNetworkDefine = 'facebook';

package/core/utils/buildTemplateString.js

@@ -33,7 +33,6 @@ exports.buildTemplateString = function buildTemplateString(template, customOptio
   template = template.replaceAll('{version}', customOptions.version);
   template = template.replaceAll('{date}', getCurrentDateFormatted());
   template = template.replaceAll('{language}', customOptions.language);
-  template = template.replaceAll('{orientation}', customOptions.orientation);
   template = template.replaceAll('{network}', networkName.toLowerCase());
   template = template.replaceAll('{hash}', '[fullhash:6]');
 

package/core/utils/getPlaycraftOrientationSuffix.js

@@ -0,0 +1,13 @@
+/**
+ * 根据当前构建的横竖屏方向版本，计算用于产物文件夹/文件命名的后缀。
+ * 命名规则：landscape → '_L'，portrait → '_P'，both（自适应）→ ''（无后缀）。
+ * @param {'both'|'landscape'|'portrait'} [orientation] - 方向版本，默认为 'both'
+ * @returns {string} 命名后缀
+ */
+function getPlaycraftOrientationSuffix(orientation) {
+  if (orientation === 'landscape') return '_L';
+  if (orientation === 'portrait') return '_P';
+  return '';
+}
+
+exports.getPlaycraftOrientationSuffix = getPlaycraftOrientationSuffix;

package/core/utils/injectSDKPlugins.js

@@ -22,14 +22,14 @@ const { SocialMediaInjectorPlugin } = require('../plugins/SocialMediaInjectorPlu
  * @param {Object} options - 配置选项
  * @param {AD_NETWORK} options.network - 广告网络
  * @param {AD_PROTOCOL} options.protocol - 广告协议
- * @param {string} [options.orientation] - 屏幕方向（google 渠道需要）
+ * @param {'both'|'landscape'|'portrait'} [options.playcraftOrientationValue] - 当前构建的横竖屏方向版本（google 渠道需要）
  * @param {string} [options.projectRoot] - 项目根目录（social_media 渠道读取 theme.data.json5 用）
  * @param {string} [options.themeName] - 当前主题名
  * @param {object} [options.themeConfig] - builds.config.js 中的 themes 配置
  * @param {object} [options.mergedData] - 预合并的主题数据（可选）
  */
 function injectSDKPlugins(webpackConfig, options) {
-  const { network: adNetwork, protocol: adProtocol, orientation, projectRoot, themeName, themeConfig, mergedData } = options;
+  const { network: adNetwork, protocol: adProtocol, playcraftOrientationValue, projectRoot, themeName, themeConfig, mergedData } = options;
 
   // 协议层注入
   if ('dapi' === adProtocol) {
@@ -44,7 +44,7 @@ function injectSDKPlugins(webpackConfig, options) {
 
   // 渠道特定注入
   if (adNetwork === 'google') {
-    webpackConfig.plugins.push(new ExitAPIInjectorPlugin(orientation));
+    webpackConfig.plugins.push(new ExitAPIInjectorPlugin(playcraftOrientationValue));
   } else if (adNetwork === 'unity') {
     // Unity Ads 使用专门的 UnityInjectorPlugin
     webpackConfig.plugins.push(new UnityInjectorPlugin());

package/core/utils/logOptions.js

@@ -22,7 +22,16 @@ exports.logOptions = function logOptions(options) {
   if (logOptions.jsConfig === 'jsconfig.json') delete logOptions.jsConfig;
   if (logOptions.buildConfig === 'build.json') delete logOptions.buildConfig;
   if (logOptions.language === 'en') delete logOptions.language;
-  if (logOptions.orientation === 'both') delete logOptions.orientation;
+  // playcraftOrientation/playcraftOrientationChannel 为默认值时不显示，避免日志噪音
+  if (Array.isArray(logOptions.playcraftOrientation) && logOptions.playcraftOrientation.length === 1 && logOptions.playcraftOrientation[0] === 'both') {
+    delete logOptions.playcraftOrientation;
+  }
+  if (Array.isArray(logOptions.playcraftOrientationChannel) && logOptions.playcraftOrientationChannel.length === 0) {
+    delete logOptions.playcraftOrientationChannel;
+  }
+  if (!logOptions.playcraftOrientationValue || logOptions.playcraftOrientationValue === 'both') {
+    delete logOptions.playcraftOrientationValue;
+  }
   // 在 dev 模式下，如果 network 为默认值 preview 则不显示
   if (!isProduction && logOptions.network === 'preview') delete logOptions.network;
   // 在 dev 模式下，如果 protocol 为默认值 none 则不显示

package/core/utils/parseArgvOptions.js

@@ -46,8 +46,8 @@ const mraidPartners = [
 /** @type {LANGUAGE[]} */
 const allowedLanguages = ['auto', 'en', 'es', 'zh', 'hi', 'ar', 'fr', 'de', 'ja', 'pt'];
 
-/** @type {ORIENTATION[]} */
-const allowedOrientations = ['both', 'portrait', 'landscape', 'square'];
+/** @type {('both'|'landscape'|'portrait')[]} playcraftOrientation 允许的横竖屏方向版本取值 */
+const allowedPlaycraftOrientations = ['both', 'landscape', 'portrait'];
 
 /**
  * Parses command line arguments based on provided options configuration
@@ -111,4 +111,4 @@ exports.allowedAdNetworks = allowedAdNetworks;
 exports.allowedAdProtocols = allowedAdProtocols;
 exports.mraidPartners = mraidPartners;
 exports.allowedLanguages = allowedLanguages;
-exports.allowedOrientations = allowedOrientations;
+exports.allowedPlaycraftOrientations = allowedPlaycraftOrientations;

package/core/webpack.build.js

@@ -19,6 +19,8 @@ const { buildTemplateString } = require('./utils/buildTemplateString.js');
 const { logOptions } = require('./utils/logOptions.js');
 const { injectSDKPlugins } = require('./utils/injectSDKPlugins.js');
 const { resolveChannelFold2Zip } = require('./utils/resolveChannelFold2Zip.js');
+const { getPlaycraftOrientationSuffix } = require('./utils/getPlaycraftOrientationSuffix.js');
+const { PlaycraftOrientationInjectorPlugin } = require('./plugins/PlaycraftOrientationInjectorPlugin.js');
 
 
 const META = {
@@ -106,6 +108,13 @@ function makeWebpackBuildConfig(customOptions, customDefines, webpackCustomConfi
   /** @type {AD_PROTOCOL} */
   const adProtocol = buildOptions['protocol'];
 
+  /** @type {'both'|'landscape'|'portrait'} 当前单次构建实际使用的横竖屏方向版本，默认 'both' */
+  const playcraftOrientationValue = buildOptions.playcraftOrientationValue || 'both';
+  /** @type {string} 方向版本对应的命名后缀：landscape→'_L'，portrait→'_P'，both→'' */
+  const orientationSuffix = getPlaycraftOrientationSuffix(playcraftOrientationValue);
+  /** @type {string} 渠道 + 方向后缀组成的产物标识，如 'google_L' */
+  const outputId = `${adNetwork}${orientationSuffix}`;
+
   let outDir = buildTemplateString(buildOptions.outDir, buildOptions);
 
   function getFileName() {
@@ -224,9 +233,11 @@ function makeWebpackBuildConfig(customOptions, customDefines, webpackCustomConfi
       plugins: [
         new HtmlWebpackPlugin(htmlWebpackPluginConfig),
         new MetaTagOverridePlugin(adNetwork),
+        // 注入 window.playcraftOrientation 全局变量，标识当前构建产物对应的横竖屏方向版本
+        new PlaycraftOrientationInjectorPlugin(playcraftOrientationValue),
 
         new webpack.DefinePlugin({
-          ...buildDefines(),
+          ...buildDefines(buildOptions),
           ...buildOptions.defines,
           ...customDefines
         }),
@@ -388,7 +399,7 @@ function makeWebpackBuildConfig(customOptions, customDefines, webpackCustomConfi
   injectSDKPlugins(webpackConfig, {
     network: adNetwork,
     protocol: adProtocol,
-    orientation: buildOptions.orientation
+    playcraftOrientationValue
   });
 
   if (isZipOutputFinal) {
@@ -418,13 +429,13 @@ function makeWebpackBuildConfig(customOptions, customDefines, webpackCustomConfi
 
     webpackConfig.plugins.push(
       new ZipPlugin({
-        filename: isChannelFold2Zip ? adNetwork : getFileName(),
+        filename: isChannelFold2Zip ? outputId : getFileName(),
         path: path.resolve(outDir),
         cleanTempFolder: true // 🗑️ 生成 zip 后删除临时文件夹
       })
     );
 
-    webpackConfig.output.path = path.resolve(outDir, adNetwork);
+    webpackConfig.output.path = path.resolve(outDir, outputId);
     if (adNetwork === 'adikteev') {
       webpackConfig.output.filename = 'creative.js';
       // Adikteev 需要将 CSS 单独提取为 style.css 文件
@@ -467,13 +478,33 @@ function runBuild(webpackConfig, customOptions, customDefines, webpackCustomConf
     if (!webpackConfig) webpackConfig = makeWebpackBuildConfig(customOptions, customDefines, webpackCustomConfig);
 
     const compiler = webpack(webpackConfig);
+
+    // 必须显式调用 compiler.close() 释放本次编译占用的内存（模块图/资源缓存/
+    // Terser 与 obfuscator 等插件持有的引用）。webpack 官方要求：若在同一进程内
+    // 多次调用 compiler.run()，每次 run 完成后都要 close，否则上一次编译的内存
+    // 无法被回收。playcraftOrientationChannel 会在同一进程里串行构建多个方向
+    // 版本（多次调用本函数），若不 close，内存会随构建次数线性累加，最终触发
+    // "JavaScript heap out of memory"。
+    const finalize = (error) => {
+      compiler.close((closeErr) => {
+        if (closeErr) {
+          console.error('关闭 webpack compiler 时出错:', closeErr);
+        }
+        if (error) {
+          reject(error);
+        } else {
+          resolve();
+        }
+      });
+    };
+
     compiler.run((err, stats) => {
       if (err) {
         console.error('Build failed:', err.stack || err);
         if (err.details) {
           console.error('Error details:', err.details);
         }
-        return reject(err);
+        return finalize(err);
       }
 
       if (stats.hasErrors()) {
@@ -491,10 +522,10 @@ function runBuild(webpackConfig, customOptions, customDefines, webpackCustomConf
         
         // 拒绝 Promise 时传递格式化的错误消息
         const errorMessage = errors.map((e, i) => `[${i + 1}] ${e.message || e}`).join('\n');
-        reject(new Error(`Webpack build failed with ${errors.length} error(s):\n${errorMessage}`));
+        finalize(new Error(`Webpack build failed with ${errors.length} error(s):\n${errorMessage}`));
       } else {
         console.log(`Build successful!`);
-        resolve();
+        finalize(null);
       }
     });
   });

package/core/webpack.dev.js

@@ -10,6 +10,7 @@ const { mergeOptions } = require('./utils/mergeOptions.js');
 const { buildDefines } = require('./utils/buildDefines.js');
 const { logOptions } = require('./utils/logOptions.js');
 const { injectSDKPlugins } = require('./utils/injectSDKPlugins.js');
+const { PlaycraftOrientationInjectorPlugin } = require('./plugins/PlaycraftOrientationInjectorPlugin.js');
 
 /**
  * Creates webpack configuration for development
@@ -24,6 +25,9 @@ function makeWebpackDevConfig(customOptions, customDefines, webpackCustomConfig)
   customDefines = customDefines || {};
   webpackCustomConfig = webpackCustomConfig || {};
 
+  /** @type {'both'|'landscape'|'portrait'} */
+  const playcraftOrientationValue = devOptions.playcraftOrientationValue || 'both';
+
   const webpackConfig = merge(
     webpackCommonConfig,
     {
@@ -47,9 +51,11 @@ function makeWebpackDevConfig(customOptions, customDefines, webpackCustomConfig)
             viewport: 'width=device-width,initial-scale=1.0,viewport-fit=cover,maximum-scale=1.0,user-scalable=no'
           }
         }),
+        // 注入 window.playcraftOrientation 全局变量，标识当前构建产物对应的横竖屏方向版本
+        new PlaycraftOrientationInjectorPlugin(playcraftOrientationValue),
 
         new webpack.DefinePlugin({
-          ...buildDefines(),
+          ...buildDefines(devOptions),
           ...devOptions.defines,
           __DEV__: JSON.stringify(devOptions['dev'] === undefined ? true : devOptions['dev']),
           ...customDefines
@@ -67,7 +73,7 @@ function makeWebpackDevConfig(customOptions, customDefines, webpackCustomConfig)
   injectSDKPlugins(webpackConfig, {
     network: devOptions['network'],
     protocol: devOptions['protocol'],
-    orientation: devOptions['orientation']
+    playcraftOrientationValue
   });
 
   return webpackConfig;

package/defines.d.ts

@@ -49,7 +49,7 @@ declare const APP: string;
 declare const NAME: string;
 declare const VERSION: string;
 declare const LANGUAGE: 'auto' | 'en' | 'es' | 'zh' | 'hi' | 'ar' | 'fr' | 'de' | 'ja' | 'pt';
-declare const ORIENTATION: 'both' | 'portrait' | 'landscape' | 'square';
+declare const PLAYCRAFT_ORIENTATION: 'both' | 'landscape' | 'portrait';
 declare const BUILD_HASH: string;
 
 declare const __DEV__: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/devkit",
-  "version": "1.0.27",
+  "version": "1.0.28",
   "description": "HTML5 Playable Ads 构建工具，支持多广告渠道打包",
   "main": "core/index.js",
   "module": "core/index.js",