@playcraft/devkit 1.0.31-beta.1 → 1.0.31-beta.11

package/README.md

@@ -0,0 +1,262 @@
+# @tencent/playable-scripts
+
+HTML5 Playable Ads 构建工具，支持多广告渠道打包。
+
+## 特性
+
+- 🚀 **一键构建** - 轻松为不同广告渠道生成构建包
+- ⚡ **自动优化** - 包含压缩、Tree-shaking 和死代码消除
+- 🗜️ **fflate 压缩** - 编译时压缩，运行时解压，体积减少 40-60%
+- 🎯 **多渠道支持** - 支持 Google Ads、Meta、AppLovin、Unity、IronSource、BigoAds 等
+- 🎨 **主题系统** - 支持多主题批量构建
+- 🔄 **并发构建** - 智能并发，大幅提升构建效率
+
+## 快速开始
+
+### 安装
+
+```bash
+tnpm install --save-dev @tencent/playable-scripts
+```
+
+### 配置 package.json
+
+```json
+{
+  "scripts": {
+    "dev": "playable-scripts dev",
+    "build": "playable-scripts build",
+    "builds": "playable-scripts builds"
+  }
+}
+```
+
+### 启动开发服务器
+
+```bash
+npm run dev                           # 默认预览模式
+npm run dev bigoads                   # 指定渠道调试（简写）
+npm run dev -- --network social_media # 指定渠道调试（完整参数）
+npm run dev -- --port 8080            # 指定端口
+```
+
+### 构建指定渠道
+
+```bash
+npm run build google        # Google Ads
+npm run build facebook      # Meta
+npm run build unity         # Unity Ads
+npm run build bigoads       # BigoAds
+```
+
+### 批量构建
+
+```bash
+npm run builds                              # 构建所有渠道
+npm run builds -- -t "theme1,theme2"        # 指定主题
+npm run builds -- -c "google,facebook"      # 指定渠道
+npm run builds -- --parallel 4              # 指定并发数
+
+# Windows PowerShell 兼容格式（推荐）
+npm run builds -- "theme1" "google"         # 位置参数：主题 渠道
+npm run builds -- --themes="theme1,theme2" --channels="google,facebook"
+```
+
+## 支持的广告渠道
+
+| 渠道 | 命令 | 协议 |
+|------|------|------|
+| Preview (预览) | `preview` | none |
+| Google Ads | `google` | none |
+| Meta (Facebook) | `facebook` | none（ZIP，仅 index.html，上限 5MB） |
+| AppLovin | `applovin` | mraid |
+| Unity Ads | `unity` | mraid |
+| IronSource | `ironsource` | mraid/dapi |
+| TikTok / Pangle | `tiktok` | none |
+| BigoAds | `bigoads` | bigo-mraid |
+| Adikteev | `adikteev` | mraid |
+| Moloco | `moloco` | none |
+| Liftoff | `liftoff` | mraid (ZIP) |
+| InMobi | `inmobi` | mraid |
+| Snapchat | `snapchat` | snapchat |
+| Remerge | `remerge` | mraid (ZIP) |
+| Mintegral | `mintegral` | none |
+
+## CLI 参数
+
+| 参数 | 描述             | 默认值       |
+|------|----------------|-----------|
+| **广告渠道** | 目标广告渠道         | `preview` |
+| `--out-dir` | 输出目录           | `dist`    |
+| `--obfuscate-level` | 代码混淆等级 (1-4)   | `4`       |
+| `--fflate-compression` | 启用 fflate 压缩   | `true`    |
+| `--protocol` | 广告协议           | 渠道自动决定    |
+| `--zip` | ZIP 输出结果       | `false`   |
+| `--port` | 开发服务器端口        | `3000`    |
+| `--open` | 自动打开浏览器        | `false`   |
+| `--language` | 语言代码           | `en`      |
+| `--is-channel-fold2zip ` | 所有渠道输出为 ZIP 结果 | `false`   |
+
+## 配置文件
+
+支持两种配置文件（推荐使用 `builds.config.js`）：
+
+### builds.config.js（推荐）
+
+```javascript
+module.exports = {
+  // 项目基本信息
+  projectName: 'My-Game',                    // 可选，默认 'Phaser Game'
+  googlePlayUrl: 'https://play.google.com/...', // 可选
+  appStoreUrl: 'https://apps.apple.com/...',    // 可选
+  
+  // 渠道配置
+  channels: ['google', 'facebook', 'unity'],    // 可选，有默认值
+  
+  // 主题配置（可选）
+  themes: {
+    enabled: true,                              // 默认 false
+    sourceDir: 'src/theme',                     // 默认 'src/theme'
+    entryFile: 'src/theme/index.ts',          // 默认 'src/theme/index.ts'
+    whitelist: null,                            // 可选，过滤函数
+  },
+  
+  // 文件命名配置（可选）
+  naming: {
+    language: 'EN',                             // 默认 'EN'
+    format: '无',                               // 默认 '无'
+    supplier: 'AIX',                            // 默认 'AIX'
+    follower: 'ZQL',                            // 默认 'ZQL'
+    generator: null,                            // 可选，自定义生成函数
+  },
+  
+  // 构建配置（可选）
+  build: {
+    outputDir: 'dist-all',                      // 默认 'dist-all'
+    tempDirPrefix: 'dist-temp',                 // 默认 'dist-temp'
+    continueOnError: true,                      // 默认 true
+    cleanTemp: true,                            // 默认 true
+    parallel: undefined,                        // 默认自动计算（CPU核心数-1，最小2最大8）
+  },
+  cosConfig: {
+    enabled: true,                              // 是否启用 COS 上传
+    SecretId: 'YOUR_SECRET_ID',                 // 腾讯云 SecretId
+    SecretKey: 'YOUR_SECRET_KEY',               // 腾讯云 SecretKey
+    Bucket: 'your-bucket-1234567890',           // COS 存储桶名称
+    Region: 'ap-guangzhou',                     // COS 区域
+    CdnDomain: 'your-cdn-domain.com',           // CDN 域名（用于生成访问链接）
+    PathPrefix: 'playable/preview',             // COS 路径前缀（可选）
+  },
+  // 打包参数（可选）
+  obfuscateLevel: 4,                            // 默认 4
+  fflateCompression: false,                      // 默认 true
+};
+```
+
+### build.json（向后兼容）
+
+```json
+{
+  "app": "AppName",
+  "name": "ConceptName",
+  "google_play_url": "https://play.google.com/...",
+  "app_store_url": "https://apps.apple.com/..."
+}
+```
+
+### 配置优先级
+
+```
+命令行参数 > build.json > builds.config.js > 默认值
+```
+
+## 代码混淆等级
+
+| 等级 | 名称 | 说明 | 体积影响 |
+|------|------|------|----------|
+| **1** | terser-only | 仅 Terser 压缩 | 基准 |
+| **2** | basic | 控制流平坦化 + 字符串编码 | +5~10% |
+| **3** | dead-code | 等级 2 + 死代码注入 | +15~25% |
+| **4** | maximum | 全部拉满（默认） | +30~50% |
+
+## fflate 压缩
+
+| 指标 | 效果 |
+|------|------|
+| **压缩率** | 66-68% |
+| **体积减少** | 40-60% |
+| **解压速度** | 3-5ms |
+| **兼容性** | 99%+ 浏览器 |
+
+## 批量构建
+
+### 特性
+
+1. **智能并发** - 自动根据 CPU 核心数优化（默认：核心数-1，最小2最大8）
+2. **独立临时目录** - 每个任务使用独立目录，避免冲突
+3. **主题切换** - 自动切换主题入口文件
+4. **错误容忍** - 单个失败不影响其他构建
+
+### 命令行参数
+
+| 参数 | 缩写 | 描述 | 示例 |
+|------|------|------|------|
+| `--themes` | `-t` | 指定主题列表（逗号分隔） | `-t "theme1,theme2"` |
+| `--channels` | `-c` | 指定渠道列表（逗号分隔） | `-c "google,facebook"` |
+| `--parallel` | `-p` | 指定并发数 | `-p 4` |
+| 位置参数 | - | 第一个参数=主题，第二个=渠道 | `"theme1" "google"` |
+| `=` 格式 | - | Windows PowerShell 兼容 | `--themes="theme1"` |
+
+**注意**：
+- **Mac/Linux**：所有格式均可使用
+- **Windows PowerShell**：推荐使用位置参数或 `--themes=value` 格式
+- **Windows CMD**：所有格式均可使用
+
+### 输出结构
+
+```
+dist-all/
+├── theme1/
+│   ├── theme1-EN-无-3月-20260304-AIX-ZQL-google.zip
+│   └── theme1-EN-无-3月-20260304-AIX-ZQL-facebook.zip
+└── theme2/
+    └── ...
+```
+
+产物直接放在主题目录下，不再套一层 `主题名_渠道名` 文件夹。文件名本身已包含渠道名。
+
+## 全局变量
+
+构建时自动注入：
+
+| 变量 | 描述 | 示例 |
+|------|------|------|
+| `__DEV__` | 开发模式标志 | `true` / `false` |
+| `AD_NETWORK` | 当前广告渠道 | `"google"`, `"bigoads"` |
+| `AD_PROTOCOL` | 当前广告协议 | `"none"`, `"mraid"` |
+| `GOOGLE_PLAY_URL` | Google Play 链接 | `"https://..."` |
+| `APP_STORE_URL` | App Store 链接 | `"https://..."` |
+
+## 配套 SDK
+
+配合 `@tencent/playable-sdk` 使用：
+
+```bash
+tnpm install @tencent/playable-sdk
+```
+
+```javascript
+import { sdk } from '@tencent/playable-sdk';
+
+sdk.init((width, height) => {
+  new Game(width, height);
+});
+
+sdk.start();              // 游戏开始
+sdk.finish();             // 游戏结束
+sdk.install();            // 跳转商店
+```
+
+## 许可证
+
+MIT License

package/cli/bin/playable-scripts.js

@@ -1,7 +1,54 @@
 #!/usr/bin/env node
-"use strict";process.on("unhandledRejection",err=>{throw err});const spawn=require("cross-spawn");const args=process.argv.slice(2);const scriptIndex=args.findIndex(x=>x==="build"||x==="dev"||x==="vite-dev"||x==="builds"||x==="pack");const script=scriptIndex===-1?args[0]:args[scriptIndex];const nodeArgs=scriptIndex>0?args.slice(0,scriptIndex):[];if(["build","dev","vite-dev","builds","pack"].includes(script)){const result=spawn.sync(process.execPath,nodeArgs.concat(require.resolve("../commands/"+script)).concat(args.slice(scriptIndex+1)),{stdio:"inherit",env:{...process.env,// 兜底：重度混淆（obfuscateLevel=4，controlFlowFlattening + deadCodeInjection
-// + LimitChunkCountPlugin 单chunk）叠加较大规模源码时，单次 webpack 编译可能
-// 占用数 GB 堆内存，默认的 V8 堆上限不足以支撑，会崩溃为
-// "JavaScript heap out of memory"。此处提高上限做防御
-// （不覆盖用户已自行设置的 NODE_OPTIONS）
-NODE_OPTIONS:process.env.NODE_OPTIONS||"--max-old-space-size=8192"}});if(result.signal){if(result.signal==="SIGKILL"){console.log("The build failed because the process exited too early. "+"This probably means the system ran out of memory or someone called "+"`kill -9` on the process.")}else if(result.signal==="SIGTERM"){console.log("The build failed because the process exited too early. "+"Someone might have called `kill` or `killall`, or the system could "+"be shutting down.")}process.exit(1)}process.exit(result.status)}else{console.log("Unknown script \""+script+"\".")}
+
+'use strict';
+
+process.on('unhandledRejection', (err) => {
+  throw err;
+});
+
+const spawn = require('cross-spawn');
+
+const args = process.argv.slice(2);
+
+const scriptIndex = args.findIndex((x) => x === 'build' || x === 'dev' || x === 'vite-dev' || x === 'builds' || x === 'pack');
+
+const script = scriptIndex === -1 ? args[0] : args[scriptIndex];
+const nodeArgs = scriptIndex > 0 ? args.slice(0, scriptIndex) : [];
+
+if (['build', 'dev', 'vite-dev', 'builds', 'pack'].includes(script)) {
+  const result = spawn.sync(
+    process.execPath,
+    nodeArgs.concat(require.resolve('../commands/' + script)).concat(args.slice(scriptIndex + 1)),
+    {
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        // 兜底：重度混淆（obfuscateLevel=4，controlFlowFlattening + deadCodeInjection
+        // + LimitChunkCountPlugin 单chunk）叠加较大规模源码时，单次 webpack 编译可能
+        // 占用数 GB 堆内存，默认的 V8 堆上限不足以支撑，会崩溃为
+        // "JavaScript heap out of memory"。此处提高上限做防御
+        // （不覆盖用户已自行设置的 NODE_OPTIONS）
+        NODE_OPTIONS: process.env.NODE_OPTIONS || '--max-old-space-size=8192'
+      }
+    }
+  );
+  if (result.signal) {
+    if (result.signal === 'SIGKILL') {
+      console.log(
+        'The build failed because the process exited too early. ' +
+          'This probably means the system ran out of memory or someone called ' +
+          '`kill -9` on the process.'
+      );
+    } else if (result.signal === 'SIGTERM') {
+      console.log(
+        'The build failed because the process exited too early. ' +
+          'Someone might have called `kill` or `killall`, or the system could ' +
+          'be shutting down.'
+      );
+    }
+    process.exit(1);
+  }
+  process.exit(result.status);
+} else {
+  console.log('Unknown script "' + script + '".');
+}

package/cli/commands/build.js

@@ -1,13 +1,67 @@
-"use strict";process.env.BABEL_ENV="production";process.env.NODE_ENV="production";const fs=require("fs");const path=require("path");const{runBuild}=require("../../core/webpack.build.js");const{runThemeValidation,restoreSchema}=require("../../core/utils/validateThemeData");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");const{isWebEngine}=require("../../core/utils/parseArgvOptions.js");const{prepareCocosTemplate,emitCocosChannel}=require("../../core/engines/cocos/pack.js");/**
+'use strict';
+
+process.env.BABEL_ENV = 'production';
+process.env.NODE_ENV = 'production';
+
+const fs = require('fs');
+const path = require('path');
+const { runBuild } = require('../../core/webpack.build.js');
+const { runThemeValidation, restoreSchema } = require('../../core/utils/validateThemeData');
+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');
+const { isWebEngine } = require('../../core/utils/parseArgvOptions.js');
+const { prepareCocosTemplate, emitCocosChannel } = require('../../core/engines/cocos/pack.js');
+
+/**
  * 从主题入口文件中检测当前主题名称。
  * 支持以下模式：
  *   export { default } from './themeName';
  *   import Theme from './themeName';
- */function detectCurrentTheme(projectRoot){// 尝试加载 builds.config.js 获取主题配置
-const buildsConfigPath=path.join(projectRoot,"builds.config.js");let themeConfig={sourceDir:"src/theme",entryFile:"src/theme/index.ts"};if(fs.existsSync(buildsConfigPath)){try{delete require.cache[buildsConfigPath];const config=require(buildsConfigPath);if(config.themes){themeConfig={...themeConfig,...config.themes}}}catch(e){// 忽略错误
-}}const entryPath=path.join(projectRoot,themeConfig.entryFile);if(!fs.existsSync(entryPath)){return{themeName:null,themeConfig}}const content=fs.readFileSync(entryPath,"utf8");// 匹配: export { default } from './themeName' 或 import ... from './themeName'
-const match=content.match(/from\s+['"]\.\/([^'"]+)['"]/);if(match){return{themeName:match[1],themeConfig}}return{themeName:null,themeConfig}}// --- 主流程 ---
-const projectRoot=process.cwd();const{themeName,themeConfig}=detectCurrentTheme(projectRoot);let schemaPathToRestore=null;let isExiting=false;// ============================================================
+ */
+function detectCurrentTheme(projectRoot) {
+  // 尝试加载 builds.config.js 获取主题配置
+  const buildsConfigPath = path.join(projectRoot, 'builds.config.js');
+  let themeConfig = { sourceDir: 'src/theme', entryFile: 'src/theme/index.ts' };
+
+  if (fs.existsSync(buildsConfigPath)) {
+    try {
+      delete require.cache[buildsConfigPath];
+      const config = require(buildsConfigPath);
+      if (config.themes) {
+        themeConfig = { ...themeConfig, ...config.themes };
+      }
+    } catch (e) {
+      // 忽略错误
+    }
+  }
+
+  const entryPath = path.join(projectRoot, themeConfig.entryFile);
+  if (!fs.existsSync(entryPath)) {
+    return { themeName: null, themeConfig };
+  }
+
+  const content = fs.readFileSync(entryPath, 'utf8');
+
+  // 匹配: export { default } from './themeName' 或 import ... from './themeName'
+  const match = content.match(/from\s+['"]\.\/([^'"]+)['"]/);
+  if (match) {
+    return { themeName: match[1], themeConfig };
+  }
+
+  return { themeName: null, themeConfig };
+}
+
+// --- 主流程 ---
+const projectRoot = process.cwd();
+const { themeName, themeConfig } = detectCurrentTheme(projectRoot);
+
+let schemaPathToRestore = null;
+let isExiting = false;
+
+// ============================================================
 // 📌 中断信号处理（Ctrl+C / kill）
 // ============================================================
 // 单主题构建过程中，theme.schema.json5 可能已被 runThemeValidation()
@@ -15,35 +69,190 @@ const projectRoot=process.cwd();const{themeName,themeConfig}=detectCurrentTheme(
 // 避免文件被强制中断而遗留在“已覆写”状态。
 // 注意：SIGKILL（kill -9）无法被捕获，属于无法规避的极端情况，
 // 此时依赖 validateThemeData.js 中的兜底检测（下次构建自动识别并降级处理）。
-function handleInterrupt(){if(isExiting)return;isExiting=true;console.log("\n\x1B[33m\u6536\u5230\u4E2D\u65AD\u4FE1\u53F7\uFF0C\u6B63\u5728\u6E05\u7406...\x1B[0m");if(schemaPathToRestore){try{restoreSchema(schemaPathToRestore);console.log("\x1B[36m\u5DF2\u6062\u590D theme.schema.json5\x1B[0m")}catch(e){console.error(`\x1b[31m恢复 theme.schema.json5 失败: ${e.message}\x1b[0m`)}schemaPathToRestore=null}process.exit(1)}process.on("SIGINT",handleInterrupt);process.on("SIGTERM",handleInterrupt);// ============================================================
+function handleInterrupt() {
+  if (isExiting) return;
+  isExiting = true;
+
+  console.log('\n\x1b[33m收到中断信号，正在清理...\x1b[0m');
+
+  if (schemaPathToRestore) {
+    try {
+      restoreSchema(schemaPathToRestore);
+      console.log('\x1b[36m已恢复 theme.schema.json5\x1b[0m');
+    } catch (e) {
+      console.error(`\x1b[31m恢复 theme.schema.json5 失败: ${e.message}\x1b[0m`);
+    }
+    schemaPathToRestore = null;
+  }
+
+  process.exit(1);
+}
+
+process.on('SIGINT', handleInterrupt);
+process.on('SIGTERM', handleInterrupt);
+
+// ============================================================
 // 📌 编译前检查（埋点验证等）
 // ============================================================
 // 支持通过环境变量控制是否跳过检查
 // - SKIP_PRE_BUILD_CHECKS=1: 强制跳过检查
 // - PLAYABLE_BATCH_MODE=1: 批量构建模式，子进程自动跳过检查（主进程已执行）
-const isBatchMode=process.env.PLAYABLE_BATCH_MODE==="1";const shouldSkipChecks=process.env.SKIP_PRE_BUILD_CHECKS==="1"||isBatchMode;async function runPreChecks(){if(shouldSkipChecks){console.log("\n\u26A0\uFE0F  \u8DF3\u8FC7\u7F16\u8BD1\u524D\u68C0\u67E5\uFF08SKIP_PRE_BUILD_CHECKS=1\uFF09\n");return}const checkResult=await runPreBuildChecks(projectRoot,{verbose:false,showDetails:true,failFast:false,themes:themeName?[themeName]:undefined,channels:options["network"]?[options["network"]]:undefined});if(!checkResult.success){console.error("\n\u274C \u7F16\u8BD1\u524D\u68C0\u67E5\u5931\u8D25\uFF0C\u7EC8\u6B62\u6784\u5EFA\u3002");console.error("\u63D0\u793A\uFF1A\u5982\u9700\u8DF3\u8FC7\u68C0\u67E5\uFF0C\u53EF\u8BBE\u7F6E\u73AF\u5883\u53D8\u91CF: SKIP_PRE_BUILD_CHECKS=1\n");process.exit(1)}}// 执行编译前检查（异步）
-runPreChecks().then(()=>{// 检查通过后继续原有流程
-continueWithBuild()}).catch(err=>{console.error("\n\u274C \u7F16\u8BD1\u524D\u68C0\u67E5\u51FA\u9519:",err);process.exit(1)});function continueWithBuild(){// 当前广告渠道（用于决定是否启用 social_media 的 OG meta 注入）
-const adNetwork=options["network"]||"";// In batch mode (PLAYABLE_BATCH_MODE=1), the parent process has already
-// executed runThemeValidation and overwritten theme.schema.json5 with merged data.
-// Running it again in child processes would cause a race condition:
-//   1. Child reads the already-overwritten schema (pure data, no "properties"/"default")
-//   2. extractDefaultsFromSchema returns {} (empty)
-//   3. Child overwrites schema with {} → file becomes empty object
-const isBatchMode=process.env.PLAYABLE_BATCH_MODE==="1";if(themeName&&!isBatchMode){const buildLog=(msg,level)=>{const colors={info:"\x1B[36m",success:"\x1B[32m",error:"\x1B[31m"};const reset="\x1B[0m";const color=colors[level]||"";console.log(`${color}[build] ${msg}${reset}`)};const{valid,schemaPath}=runThemeValidation(themeName,projectRoot,themeConfig,{log:buildLog});schemaPathToRestore=schemaPath;if(!valid){// 校验失败时恢复 schema（备份可能已创建）
-if(schemaPathToRestore)restoreSchema(schemaPathToRestore);process.exit(1)}}// ============================================================
-// 📌 横竖屏方向多版本构建
-// ============================================================
-// 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"];/**
+const isBatchMode = process.env.PLAYABLE_BATCH_MODE === '1';
+const shouldSkipChecks = process.env.SKIP_PRE_BUILD_CHECKS === '1' || isBatchMode;
+
+async function runPreChecks() {
+  if (shouldSkipChecks) {
+    console.log('\n⚠️  跳过编译前检查（SKIP_PRE_BUILD_CHECKS=1）\n');
+    return;
+  }
+
+  const checkResult = await runPreBuildChecks(projectRoot, {
+    verbose: false,
+    showDetails: true,
+    failFast: false,
+    themes: themeName ? [themeName] : undefined,
+    channels: options['network'] ? [options['network']] : undefined,
+    engine: options.engine,
+  });
+
+  if (!checkResult.success) {
+    console.error('\n❌ 编译前检查失败，终止构建。');
+    console.error('提示：如需跳过检查，可设置环境变量: SKIP_PRE_BUILD_CHECKS=1\n');
+    process.exit(1);
+  }
+}
+
+// 执行编译前检查（异步）
+runPreChecks().then(() => {
+  // 检查通过后继续原有流程
+  continueWithBuild();
+}).catch((err) => {
+  console.error('\n❌ 编译前检查出错:', err);
+  process.exit(1);
+});
+
+function continueWithBuild() {
+  // 当前广告渠道（用于决定是否启用 social_media 的 OG meta 注入）
+  const adNetwork = options['network'] || '';
+
+  // In batch mode (PLAYABLE_BATCH_MODE=1), the parent process has already
+  // executed runThemeValidation and overwritten theme.schema.json5 with merged data.
+  // Running it again in child processes would cause a race condition:
+  //   1. Child reads the already-overwritten schema (pure data, no "properties"/"default")
+  //   2. extractDefaultsFromSchema returns {} (empty)
+  //   3. Child overwrites schema with {} → file becomes empty object
+  const isBatchMode = process.env.PLAYABLE_BATCH_MODE === '1';
+
+  if (themeName && !isBatchMode) {
+    const buildLog = (msg, level) => {
+      const colors = { info: '\x1b[36m', success: '\x1b[32m', error: '\x1b[31m' };
+      const reset = '\x1b[0m';
+      const color = colors[level] || '';
+      console.log(`${color}[build] ${msg}${reset}`);
+    };
+
+    const { valid, schemaPath } = runThemeValidation(themeName, projectRoot, themeConfig, { log: buildLog });
+    schemaPathToRestore = schemaPath;
+
+    if (!valid) {
+      // 校验失败时恢复 schema（备份可能已创建）
+      if (schemaPathToRestore) restoreSchema(schemaPathToRestore);
+      process.exit(1);
+    }
+  }
+
+  // ============================================================
+  // 📌 横竖屏方向多版本构建
+  // ============================================================
+  // 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;if(!isWebEngine(options.engine)){await runCocosBuild({playcraftOrientationValue:orientationValue,filename:suffix?`${options.filename}${suffix}`:options.filename,themeName});return}await runBuild(undefined,{playcraftOrientationValue:orientationValue,filename:suffix?`${options.filename}${suffix}`:options.filename},undefined,{plugins:[...(fontPlugin?[fontPlugin]:[]),...(socialMediaPlugin?[socialMediaPlugin]:[])]})}(async()=>{try{if(!isWebEngine(options.engine)){const templateHtml=await prepareCocosTemplate({playcraftOrientationValue:buildOrientations[0]||"both"});for(const orientationValue of buildOrientations){const suffix=getPlaycraftOrientationSuffix(orientationValue);if(buildOrientations.length>1){console.log(`\n📱 开始构建方向版本: ${orientationValue}${suffix?` (后缀: ${suffix})`:""}`)}await emitCocosChannel(templateHtml,{playcraftOrientationValue:orientationValue,filename:suffix?`${options.filename}${suffix}`:options.filename,themeName})}}else{for(const orientationValue of buildOrientations){await buildOneOrientation(orientationValue)}}if(schemaPathToRestore)restoreSchema(schemaPathToRestore);// 主动退出进程，避免 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)}})()}
+   */
+  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;
+
+    if (!isWebEngine(options.engine)) {
+      await runCocosBuild({
+        playcraftOrientationValue: orientationValue,
+        filename: suffix ? `${options.filename}${suffix}` : options.filename,
+        themeName,
+      });
+      return;
+    }
+
+    await runBuild(
+      undefined,
+      {
+        playcraftOrientationValue: orientationValue,
+        filename: suffix ? `${options.filename}${suffix}` : options.filename
+      },
+      undefined,
+      {
+        plugins: [
+          ...(fontPlugin ? [fontPlugin] : []),
+          ...(socialMediaPlugin ? [socialMediaPlugin] : []),
+        ],
+      }
+    );
+  }
+
+  (async () => {
+    try {
+      if (!isWebEngine(options.engine)) {
+        const templateHtml = await prepareCocosTemplate({
+          playcraftOrientationValue: buildOrientations[0] || 'both',
+        });
+        for (const orientationValue of buildOrientations) {
+          const suffix = getPlaycraftOrientationSuffix(orientationValue);
+          if (buildOrientations.length > 1) {
+            console.log(`\n📱 开始构建方向版本: ${orientationValue}${suffix ? ` (后缀: ${suffix})` : ''}`);
+          }
+          await emitCocosChannel(templateHtml, {
+            playcraftOrientationValue: orientationValue,
+            filename: suffix ? `${options.filename}${suffix}` : options.filename,
+            themeName,
+          });
+        }
+      } else {
+        for (const orientationValue of buildOrientations) {
+          await buildOneOrientation(orientationValue);
+        }
+      }
+
+      if (schemaPathToRestore) restoreSchema(schemaPathToRestore);
+
+      // 主动退出进程，避免 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/cli/commands/builds.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
-"use strict";/**
+
+'use strict';
+
+/**
  * Batch Builds Command for playable-scripts
  * 
  * 支持：
@@ -13,4 +16,12 @@
  * playable-scripts builds -c "google,facebook"        # 指定渠道
  * playable-scripts builds -t "theme1" -c "google"     # 指定主题和渠道
  * playable-scripts builds --parallel 3                 # 设置并发数
- */process.on("unhandledRejection",err=>{throw err});const{buildBatch}=require("../../core/batch-build");buildBatch();
+ */
+
+process.on('unhandledRejection', (err) => {
+  throw err;
+});
+
+const { buildBatch } = require('../../core/batch-build');
+
+buildBatch();

package/cli/commands/dev.js

@@ -1 +1,22 @@
-"use strict";process.env.BABEL_ENV="development";process.env.NODE_ENV="development";const{options}=require("../../core/options.js");const{isWebEngine}=require("../../core/utils/parseArgvOptions.js");if(!isWebEngine(options.engine)){const{runCocosDev}=require("../../core/engines/cocos/dev-server.js");runCocosDev({projectRoot:process.cwd(),port:process.env.PREVIEW_PORT||options.port||3000,cmd:process.argv[2]||"start"}).catch(err=>{console.error(err);process.exit(1)})}else{const{runDev}=require("../../core/webpack.dev.js");runDev()}
+'use strict';
+
+process.env.BABEL_ENV = 'development';
+process.env.NODE_ENV = 'development';
+
+const { options } = require('../../core/options.js');
+const { isWebEngine } = require('../../core/utils/parseArgvOptions.js');
+
+if (!isWebEngine(options.engine)) {
+  const { runCocosDev } = require('../../core/engines/cocos/dev-server.js');
+  runCocosDev({
+    projectRoot: process.cwd(),
+    port: process.env.PREVIEW_PORT || options.port || 3000,
+    cmd: process.argv[2] || 'start',
+  }).catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+} else {
+  const { runDev } = require('../../core/webpack.dev.js');
+  runDev();
+}