@playcraft/build 0.0.4 → 0.0.8

package/dist/vite/plugin-playcanvas.js

@@ -16,31 +16,65 @@ export function vitePlayCanvasPlugin(options) {
             // 保存插件的 this 上下文
             pluginContext = this;
         },
-        async transformIndexHtml(html) {
-            if (options.ammoReplacement) {
-                html = await injectPhysicsLibrary(html, options);
-            }
-            if (options.outputFormat === 'html') {
-                // 1. 内联 PlayCanvas Engine + 引擎补丁
-                html = await inlineEngineScript(html, options.baseBuildDir, options);
-                // 2. 内联 __game-scripts.js（用户脚本）
-                if (options.inlineGameScripts) {
-                    html = await inlineGameScripts(html, options.baseBuildDir);
+        // 使用 transformIndexHtml 的对象形式，指定在 pre 阶段执行
+        // 这确保在 Vite 处理资源引用之前移除不需要的引用
+        transformIndexHtml: {
+            order: 'pre',
+            async handler(html) {
+                if (options.ammoReplacement) {
+                    html = await injectPhysicsLibrary(html, options);
                 }
-                // 3. 内联并转换 __settings__.js（传递插件上下文）
-                html = await inlineAndConvertSettings(html, options.baseBuildDir, options, pluginContext);
-                // 4. 内联 __modules__.js
-                html = await inlineModulesScript(html, options.baseBuildDir);
-                // 5. 内联 __start__.js
-                html = await inlineStartScript(html, options.baseBuildDir, options);
-                // 6. 内联 __loading__.js
-                html = await inlineLoadingScript(html, options.baseBuildDir);
-                // 7. 内联 CSS
-                html = await inlineCSS(html, options.baseBuildDir, options);
-                // 8. 处理 manifest.json
-                html = await inlineManifest(html, options.baseBuildDir, options);
-            }
-            return html;
+                // ⚠️ 在最早期移除 manifest 引用，避免 Vite 将其作为资源处理
+                if (options.outputFormat === 'html' && options.convertDataUrls) {
+                    html = html.replace(/<link[^>]*rel=["']manifest["'][^>]*>/gi, '');
+                }
+                if (options.outputFormat === 'html') {
+                    // 1. 内联 PlayCanvas Engine + 引擎补丁
+                    html = await inlineEngineScript(html, options.baseBuildDir, options);
+                    // 2. 根据模式处理用户脚本
+                    if (options.buildMode === 'esm' && options.isESMBundle) {
+                        // ESM → IIFE：脚本已被 viteESMBundlePlugin 打包并注入到 HTML
+                        // ESM 模式的 index.esm.mjs 已包含完整的初始化逻辑，不需要 __start__.js 等
+                        console.log('[PlayCanvasPlugin] ESM Bundle 模式：脚本由 ESMBundle 插件处理');
+                        // ⚠️ 重要：ESM Bundle 模式也需要将 config.json 和场景资源内联到打包后的代码中
+                        // 因为打包后的 IIFE 代码中 CONFIG_FILENAME = "config.json" 是硬编码的
+                        html = await inlineESMBundleAssets(html, options.baseBuildDir, options, pluginContext);
+                        // 处理 CSS 和 manifest
+                        html = await inlineCSS(html, options.baseBuildDir, options);
+                        html = await inlineManifest(html, options.baseBuildDir, options);
+                    }
+                    else {
+                        // Classic 模式或 ESM 原生模式
+                        if (options.buildMode === 'classic' && options.inlineGameScripts) {
+                            // Classic 模式：内联 __game-scripts.js
+                            html = await inlineGameScripts(html, options.baseBuildDir);
+                        }
+                        // ESM 原生模式：保持 <script type="module"> 和 import map
+                        // 3. 内联并转换 __settings__.js（传递插件上下文）
+                        html = await inlineAndConvertSettings(html, options.baseBuildDir, options, pluginContext);
+                        // 4. 内联 __modules__.js
+                        html = await inlineModulesScript(html, options.baseBuildDir);
+                        // 5. 内联 __start__.js
+                        html = await inlineStartScript(html, options.baseBuildDir, options);
+                        // 6. 内联 __loading__.js
+                        html = await inlineLoadingScript(html, options.baseBuildDir);
+                        // 7. 内联 CSS
+                        html = await inlineCSS(html, options.baseBuildDir, options);
+                        // 8. 处理 manifest.json
+                        html = await inlineManifest(html, options.baseBuildDir, options);
+                    }
+                }
+                else if (options.outputFormat === 'zip') {
+                    // ZIP 格式：不内联引擎，但需要在 IIFE 之前添加引擎脚本标签
+                    if (options.buildMode === 'esm' && options.isESMBundle) {
+                        // ESM → IIFE 模式：IIFE 依赖全局 pc 变量，需要先加载引擎
+                        console.log('[PlayCanvasPlugin] ZIP + ESM Bundle 模式：添加引擎脚本标签');
+                        html = addEngineScriptTag(html);
+                    }
+                    // 对于 Classic 模式或 ESM 原生模式，保持原有的多文件结构
+                }
+                return html;
+            },
         },
         async transform(code, id) {
             // 转换 __settings__.js 中的资源路径为 data URLs（传递插件上下文）
@@ -55,11 +89,20 @@ export function vitePlayCanvasPlugin(options) {
  * 内联 PlayCanvas Engine
  */
 async function inlineEngineScript(html, baseBuildDir, options) {
-    const engineNames = [
+    // Classic 模式的引擎文件名
+    const classicEngineNames = [
         'playcanvas-stable.min.js',
         'playcanvas.min.js',
         '__lib__.js',
     ];
+    // ESM 模式的引擎文件位置
+    const esmEngineNames = [
+        'js/playcanvas-engine-umd.js',
+    ];
+    // 根据构建模式选择引擎文件列表
+    const engineNames = options.buildMode === 'esm' && options.isESMBundle
+        ? [...esmEngineNames, ...classicEngineNames] // ESM 优先，然后 Classic
+        : classicEngineNames;
     for (const engineName of engineNames) {
         const enginePath = path.join(baseBuildDir, engineName);
         try {
@@ -69,7 +112,15 @@ async function inlineEngineScript(html, baseBuildDir, options) {
             const engineScript = options.compressEngine
                 ? `${await getLz4InlineScript()}${await buildCompressedEngineScript(engineCode)}`
                 : `<script>${engineCode}</script>`;
-            // 替换 script 标签
+            // 对于 ESM 模式，引擎需要在 </head> 之前插入（确保在用户脚本之前加载）
+            if (options.buildMode === 'esm' && options.isESMBundle) {
+                // ESM 模式：在 </head> 之前插入引擎脚本
+                // 这确保 window.pc 在 IIFE 用户脚本执行前已设置
+                html = html.replace('</head>', `${engineScript}${patchScripts}\n</head>`);
+                console.log(`[PlayCanvasPlugin] ESM 模式：已内联引擎 ${engineName}`);
+                return html;
+            }
+            // Classic 模式：替换原有的 script 标签
             const scriptPattern = new RegExp(`<script[^>]*src=["']${engineName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["'][^>]*></script>`, 'i');
             html = html.replace(scriptPattern, `${engineScript}${patchScripts}`);
             return html;
@@ -80,6 +131,18 @@ async function inlineEngineScript(html, baseBuildDir, options) {
     }
     return html;
 }
+/**
+ * 为 ZIP 格式添加引擎脚本标签（不内联）
+ * 用于 ESM → IIFE 模式，IIFE 依赖全局 pc 变量
+ */
+function addEngineScriptTag(html) {
+    // 在 </head> 之前添加引擎脚本标签
+    // UMD 版本会设置 window.pc 全局变量
+    const engineScriptTag = `<script src="./js/playcanvas-engine-umd.js"></script>`;
+    html = html.replace('</head>', `${engineScriptTag}\n</head>`);
+    console.log('[PlayCanvasPlugin] ZIP 模式：已添加引擎脚本标签');
+    return html;
+}
 /**
  * 内联并转换 __settings__.js
  */
@@ -165,6 +228,231 @@ window.PRELOAD_MODULES = ${JSON.stringify(preloadModules)};
     html = html.replace('</head>', `<script>${settingsCode}</script>\n</head>`);
     return html;
 }
+/**
+ * ESM Bundle 模式专用：将 config.json 和场景资源内联到打包后的 IIFE 代码中
+ *
+ * 在 ESM Bundle 模式下，index.esm.mjs 已经被打包为 IIFE 并注入到 HTML 的 <script> 标签中
+ * 该 IIFE 代码中 CONFIG_FILENAME = "config.json" 是硬编码的字符串
+ * 此函数需要将其替换为内联的 data URL，使得单文件 HTML 可以正常工作
+ */
+async function inlineESMBundleAssets(html, baseBuildDir, options, pluginContext) {
+    console.log('[PlayCanvasPlugin] ESM Bundle 模式：开始内联 config.json 和场景资源...');
+    // 1. 读取并处理 config.json
+    const configPath = path.join(baseBuildDir, 'config.json');
+    let configJson;
+    try {
+        const configContent = await fs.readFile(configPath, 'utf-8');
+        configJson = JSON.parse(configContent);
+    }
+    catch (error) {
+        console.warn(`[PlayCanvasPlugin] ESM Bundle: 无法读取 config.json: ${error}`);
+        return html;
+    }
+    // 2. 内联 config.json 中的所有资源 URL
+    if (options.convertDataUrls) {
+        configJson = await inlineConfigAssetUrls(configJson, baseBuildDir, pluginContext);
+    }
+    // 3. 处理 Ammo 物理引擎替换
+    if (options.ammoReplacement) {
+        configJson = stripAmmoAssets(configJson);
+    }
+    // 4. 应用 MRAID 配置
+    if (options.mraidSupport) {
+        configJson = applyMraidConfig(configJson);
+    }
+    // 5. 生成 config data URL
+    const configDataUrl = `data:application/json;base64,${Buffer.from(JSON.stringify(configJson)).toString('base64')}`;
+    // 6. 处理场景文件 - 获取第一个场景的 data URL
+    let sceneDataUrl = '';
+    if (configJson.scenes && configJson.scenes.length > 0) {
+        const sceneUrl = configJson.scenes[0].url;
+        if (sceneUrl && !sceneUrl.startsWith('data:')) {
+            const scenePath = path.join(baseBuildDir, sceneUrl);
+            try {
+                const sceneContent = await fs.readFile(scenePath, 'utf-8');
+                sceneDataUrl = `data:application/json;base64,${Buffer.from(sceneContent).toString('base64')}`;
+                console.log(`[PlayCanvasPlugin] ESM Bundle: 场景已内联: ${sceneUrl}`);
+            }
+            catch (error) {
+                console.warn(`[PlayCanvasPlugin] ESM Bundle: 场景文件不存在: ${sceneUrl}`);
+            }
+        }
+        else {
+            sceneDataUrl = sceneUrl || '';
+        }
+    }
+    // 7. 内联 logo.png
+    // index.esm.mjs 中使用 `${ASSET_PREFIX}logo.png` 引用 logo
+    // 需要将 ASSET_PREFIX 替换为 data URL 或直接替换 logo 引用
+    if (options.convertDataUrls) {
+        const logoPath = path.join(baseBuildDir, 'logo.png');
+        try {
+            const logoBuffer = await fs.readFile(logoPath);
+            const logoDataUrl = `data:image/png;base64,${logoBuffer.toString('base64')}`;
+            // 替换 `${ASSET_PREFIX}logo.png` 模式
+            // 由于代码被打包为 IIFE，模板字符串可能被转换为字符串拼接
+            // 格式1: `${ASSET_PREFIX}logo.png`
+            // 格式2: ASSET_PREFIX + "logo.png"
+            // 格式3: "".concat(ASSET_PREFIX, "logo.png")  (Vite 打包后)
+            const escapedLogoDataUrl = logoDataUrl.replace(/\$/g, '$$$$');
+            // 替换模板字符串格式（原始格式）
+            html = html.replace(/\$\{ASSET_PREFIX\}logo\.png/g, escapedLogoDataUrl);
+            // 替换字符串拼接格式
+            html = html.replace(/ASSET_PREFIX\s*\+\s*["']logo\.png["']/g, `"${escapedLogoDataUrl}"`);
+            // 替换 concat 格式 (Vite/Rollup 打包后常见格式)
+            html = html.replace(/["']?["']?\.concat\(ASSET_PREFIX,\s*["']logo\.png["']\)/g, `"${escapedLogoDataUrl}"`);
+            // 替换反引号模板字符串在 IIFE 中的编译结果
+            // `${ASSET_PREFIX}logo.png` 可能被编译为 ASSET_PREFIX+"logo.png"
+            html = html.replace(/`\$\{ASSET_PREFIX\}logo\.png`/g, `"${escapedLogoDataUrl}"`);
+            // ⚠️ 重要：Vite 压缩后，直接查找 "logo.png" 字符串
+            // 格式: .src="logo.png" 或 src:"logo.png" 或 ="logo.png"
+            const logoReplaceCount = (html.match(/["']logo\.png["']/g) || []).length;
+            if (logoReplaceCount > 0) {
+                html = html.replace(/["']logo\.png["']/g, `"${escapedLogoDataUrl}"`);
+                console.log(`[PlayCanvasPlugin] ESM Bundle: 替换了 ${logoReplaceCount} 处 "logo.png" 字符串`);
+            }
+            console.log(`[PlayCanvasPlugin] ESM Bundle: logo.png 已内联`);
+        }
+        catch (error) {
+            console.warn(`[PlayCanvasPlugin] ESM Bundle: logo.png 不存在，跳过内联`);
+        }
+    }
+    // 8. 在 HTML 中查找并替换 ESM Bundle IIFE 代码中的配置值
+    // CONFIG_FILENAME = "config.json" → CONFIG_FILENAME = "data:application/json;base64,..."
+    // 注意：替换字符串中的 $ 是特殊字符，需要转义
+    const escapedConfigDataUrl = configDataUrl.replace(/\$/g, '$$$$');
+    // 替换 CONFIG_FILENAME（支持多种格式）
+    // 格式1: const CONFIG_FILENAME = "config.json"
+    // 格式2: CONFIG_FILENAME="config.json"
+    html = html.replace(/CONFIG_FILENAME\s*=\s*["']config\.json["']/g, `CONFIG_FILENAME = "${escapedConfigDataUrl}"`);
+    // ⚠️ 重要：Vite 压缩后，变量名会被混淆（如 CONFIG_FILENAME → vh）
+    // 需要直接替换 .configure("config.json" 调用中的字符串字面量
+    // 格式: .configure("config.json", ...) 或 .configure('config.json', ...)
+    const configureReplaceCount = (html.match(/\.configure\s*\(\s*["']config\.json["']/g) || []).length;
+    if (configureReplaceCount > 0) {
+        html = html.replace(/\.configure\s*\(\s*["']config\.json["']/g, `.configure("${escapedConfigDataUrl}"`);
+        console.log(`[PlayCanvasPlugin] ESM Bundle: 替换了 ${configureReplaceCount} 处 .configure("config.json") 调用`);
+    }
+    // 9. 替换 SCENE_PATH
+    if (sceneDataUrl) {
+        const escapedSceneDataUrl = sceneDataUrl.replace(/\$/g, '$$$$');
+        // 查找 SCENE_PATH 的各种格式并替换
+        // 格式: const SCENE_PATH = "xxx.json" 或 SCENE_PATH = "xxx"
+        html = html.replace(/SCENE_PATH\s*=\s*["'][^"']+\.json["']/g, `SCENE_PATH = "${escapedSceneDataUrl}"`);
+        // ⚠️ Vite 压缩后格式：loadScene("xxx.json" 或 loadScene(变量名,
+        // 需要同时替换 loadScene 调用中的场景路径字符串
+        // 格式1: .loadScene("2412781.json", ...)
+        // 格式2: .loadScene(变量名, ...) - 需要替换变量定义
+        const sceneUrl = configJson.scenes?.[0]?.url;
+        if (sceneUrl && !sceneUrl.startsWith('data:')) {
+            // 直接替换 loadScene 中的场景路径字符串
+            const scenePathRegex = new RegExp(`\\.loadScene\\s*\\(\\s*["']${sceneUrl.replace(/\./g, '\\.')}["']`, 'g');
+            const loadSceneReplaceCount = (html.match(scenePathRegex) || []).length;
+            if (loadSceneReplaceCount > 0) {
+                html = html.replace(scenePathRegex, `.loadScene("${escapedSceneDataUrl}"`);
+                console.log(`[PlayCanvasPlugin] ESM Bundle: 替换了 ${loadSceneReplaceCount} 处 .loadScene("${sceneUrl}") 调用`);
+            }
+            // 同时替换压缩后的变量定义：const vh="2412781.json" 或 变量名="2412781.json"
+            // 这会处理如 const vh="2412781.json" 这种情况
+            const varDefRegex = new RegExp(`(\\w{1,3})\\s*=\\s*["']${sceneUrl.replace(/\./g, '\\.')}["']`, 'g');
+            const varDefReplaceCount = (html.match(varDefRegex) || []).length;
+            if (varDefReplaceCount > 0) {
+                html = html.replace(varDefRegex, `$1="${escapedSceneDataUrl}"`);
+                console.log(`[PlayCanvasPlugin] ESM Bundle: 替换了 ${varDefReplaceCount} 处场景路径变量定义`);
+            }
+        }
+    }
+    // 10. 处理 PRELOAD_MODULES（WASM 模块）
+    // 在 ESM Bundle 模式下，需要将 PRELOAD_MODULES 中的 URL 也转换为 data URL
+    const modulesRegex = /PRELOAD_MODULES\s*=\s*(\[[\s\S]*?\]);/;
+    const modulesMatch = html.match(modulesRegex);
+    if (modulesMatch) {
+        try {
+            const modulesStr = modulesMatch[1];
+            let modules = new Function(`return ${modulesStr}`)();
+            // 过滤 Ammo 模块
+            if (options.ammoReplacement) {
+                modules = modules.filter((module) => !isAmmoModule(module));
+            }
+            // 转换模块 URL 为 data URL
+            for (const module of modules) {
+                if (module.fallbackUrl && !module.fallbackUrl.startsWith('data:')) {
+                    const fallbackPath = path.join(baseBuildDir, module.fallbackUrl);
+                    try {
+                        const fallbackCode = await fs.readFile(fallbackPath, 'utf-8');
+                        module.fallbackUrl = `data:text/javascript;base64,${Buffer.from(fallbackCode).toString('base64')}`;
+                        // 清空 WASM URL，强制使用 fallback
+                        module.glueUrl = '';
+                        module.wasmUrl = '';
+                    }
+                    catch (error) {
+                        console.warn(`[PlayCanvasPlugin] ESM Bundle: 无法读取 fallback: ${module.fallbackUrl}`);
+                    }
+                }
+            }
+            // 替换 PRELOAD_MODULES
+            const newModulesStr = JSON.stringify(modules);
+            const escapedModulesStr = newModulesStr.replace(/\$/g, '$$$$');
+            html = html.replace(modulesRegex, `PRELOAD_MODULES = ${escapedModulesStr};`);
+        }
+        catch (error) {
+            console.warn(`[PlayCanvasPlugin] ESM Bundle: 无法处理 PRELOAD_MODULES: ${error}`);
+        }
+    }
+    // 11. 注入 ScriptHandler 补丁（参考 PlayCanvas 官方 one-page-inline-game-scripts.js）
+    // 这个补丁覆盖 pc.ScriptHandler.prototype._loadScript，使其能够：
+    // 1. 正确处理 data URL 格式的脚本
+    // 2. 对于空脚本（已打包到 IIFE 中的），直接跳过执行
+    const scriptHandlerPatch = `
+<script>
+// ScriptHandler patch for one-page build (empty scripts are already bundled in IIFE)
+(function() {
+    if (typeof pc === 'undefined' || !pc.ScriptHandler) return;
+    
+    var originalLoadScript = pc.ScriptHandler.prototype._loadScript;
+    pc.ScriptHandler.prototype._loadScript = function(url, callback) {
+        // Check if this is a data URL
+        if (url && url.startsWith('data:text/javascript;base64,')) {
+            var head = document.head;
+            var element = document.createElement('script');
+            this._cache[url] = element;
+            element.async = false;
+            
+            // Decode base64 content
+            var index = url.indexOf(',');
+            var base64 = url.slice(index + 1);
+            
+            // If empty content (scripts already bundled), skip execution
+            if (!base64 || base64.length === 0) {
+                // Still create the element for cache consistency
+                callback(null, url, element);
+                return;
+            }
+            
+            try {
+                var data = window.atob(base64);
+                element.innerText = data;
+                head.appendChild(element);
+            } catch (e) {
+                console.warn('[ScriptHandler] Failed to decode script:', e);
+            }
+            
+            callback(null, url, element);
+            return;
+        }
+        
+        // Fall back to original implementation for non-data URLs
+        return originalLoadScript.call(this, url, callback);
+    };
+})();
+</script>`;
+    // 将补丁注入到 </head> 之前，确保在引擎之后、脚本加载之前执行
+    if (html.includes('</head>')) {
+        html = html.replace('</head>', `${scriptHandlerPatch}\n</head>`);
+    }
+    console.log('[PlayCanvasPlugin] ESM Bundle 模式：资源内联完成');
+    return html;
+}
 /**
  * 转换 settings 代码中的资源URL为 data URLs
  */
@@ -382,6 +670,24 @@ async function inlineModulesScript(html, baseBuildDir) {
  * 注意：脚本需要在 pc.AppBase 创建后执行，所以插入到 </body> 之前
  * 同时包装成一个函数，在 DOMContentLoaded 后执行，确保 PlayCanvas 引擎已完全初始化
  */
+/**
+ * 注入打包后的游戏脚本（ESM → IIFE 场景）
+ */
+async function injectBundledGameScripts(html, baseBuildDir) {
+    const gameScriptsPath = path.join(baseBuildDir, '__game-scripts.js');
+    try {
+        await fs.access(gameScriptsPath);
+        const gameScriptsCode = await fs.readFile(gameScriptsPath, 'utf-8');
+        // 在 PlayCanvas Engine 之后、__start__.js 之前插入
+        if (html.includes('</head>')) {
+            html = html.replace('</head>', `<script>${gameScriptsCode}</script>\n</head>`);
+        }
+    }
+    catch (error) {
+        console.warn('[PlayCanvasPlugin] 未找到打包后的游戏脚本');
+    }
+    return html;
+}
 async function inlineGameScripts(html, baseBuildDir) {
     const gameScriptsPath = path.join(baseBuildDir, '__game-scripts.js');
     try {
@@ -599,6 +905,7 @@ async function inlineConfigAssetUrls(configJson, baseBuildDir, pluginContext) {
     const skippedAssets = [];
     const optimizedAssets = [];
     const skippedScripts = [];
+    const missingAssets = []; // 新增：缺失资源列表
     const SIZE_LIMIT = 1 * 1024 * 1024; // 1MB - 跳过超过这个大小的文件
     for (const [assetId, asset] of Object.entries(assets)) {
         const file = asset?.file;
@@ -611,11 +918,32 @@ async function inlineConfigAssetUrls(configJson, baseBuildDir, pluginContext) {
         }
         const cleanUrl = url.split('?')[0];
         const fileName = cleanUrl.toLowerCase();
-        // 跳过指向 __game-scripts.js 的脚本资源
-        // 这些资源已经被打包到 __game-scripts.js 中，不需要单独内联
-        // __game-scripts.js 会通过 transformIndexHtml 钩子内联到 HTML 中
-        if (cleanUrl === '__game-scripts.js' || asset.type === 'script') {
+        // ⚠️ 脚本资源特殊处理（参考 PlayCanvas 官方 one-page.js 实现）
+        // ESM Bundle 模式下，脚本代码已被打包到 IIFE 中执行
+        // PlayCanvas 官方做法：将脚本内容设为空，配合引擎补丁跳过执行
+        if (cleanUrl === '__game-scripts.js') {
+            // __game-scripts.js 是 Classic 模式的打包产物
+            skippedScripts.push(asset.name || assetId);
+            // 使用空内容的 data URL（PlayCanvas 官方做法）
+            file.url = 'data:text/javascript;base64,';
+            file.hash = '';
+            asset.preload = false;
+            continue;
+        }
+        if (asset.type === 'script') {
             skippedScripts.push(asset.name || assetId);
+            // ⚠️ ESM 脚本特殊处理（参考 PlayCanvas 官方 one-page.js）：
+            // 官方工具对于 loadingType !== 0 的脚本，会将内容设为空字符串
+            // 然后配合 one-page-inline-game-scripts.js 引擎补丁处理
+            // 
+            // 我们的方案：
+            // 1. 将脚本 URL 设为空内容的 data URL
+            // 2. 清空 hash 避免追加查询参数
+            // 3. 脚本代码已经通过 IIFE 中的 pc.createScript() 注册
+            // 4. 需要配合引擎补丁让 ScriptHandler 跳过空脚本
+            file.url = 'data:text/javascript;base64,'; // 空 JavaScript
+            file.hash = ''; // 清空 hash
+            asset.preload = false; // 禁用预加载
             continue;
         }
         // 跳过物理引擎缓存文件和大型文本文件
@@ -626,8 +954,8 @@ async function inlineConfigAssetUrls(configJson, baseBuildDir, pluginContext) {
             skippedAssets.push(`${asset.name || assetId} (${(file.size / 1024 / 1024).toFixed(2)}MB)`);
             // 标记为不预加载，避免引擎尝试加载
             asset.preload = false;
-            // 清空 URL，避免加载失败
-            file.url = 'data:text/plain;base64,';
+            // 提供有效的占位符数据，避免解析错误
+            file.url = getPlaceholderDataUrl(asset.type, fileName);
             continue;
         }
         const fullPath = path.join(baseBuildDir, cleanUrl);
@@ -635,26 +963,76 @@ async function inlineConfigAssetUrls(configJson, baseBuildDir, pluginContext) {
             // ✅ 简化逻辑：直接读取文件并判断是否需要压缩
             const buffer = await fs.readFile(fullPath);
             const originalSize = buffer.length;
+            // 检查空文件，提供有效的占位符
+            if (originalSize === 0) {
+                console.warn(`⚠️  警告: 文件为空，使用占位符: ${asset.name || cleanUrl}`);
+                file.url = getPlaceholderDataUrl(asset.type, fileName);
+                file.size = 0;
+                continue;
+            }
             // 检查实际文件大小，跳过超大文件
             if (originalSize > SIZE_LIMIT) {
                 skippedAssets.push(`${asset.name || assetId} (${(originalSize / 1024 / 1024).toFixed(2)}MB)`);
                 asset.preload = false;
-                file.url = 'data:text/plain;base64,';
+                // 提供有效的占位符数据，避免解析错误
+                file.url = getPlaceholderDataUrl(asset.type, fileName);
                 continue;
             }
             let dataUrl;
             let finalSize;
+            // 处理 JSON 文件：去除注释和尾随逗号，验证格式
+            if (asset.type === 'json' || fileName.endsWith('.json')) {
+                try {
+                    let jsonText = buffer.toString('utf-8');
+                    // 移除单行注释 // ...
+                    jsonText = jsonText.replace(/\/\/.*$/gm, '');
+                    // 移除多行注释 /* ... */
+                    jsonText = jsonText.replace(/\/\*[\s\S]*?\*\//g, '');
+                    // 移除尾随逗号
+                    jsonText = jsonText.replace(/,(\s*[}\]])/g, '$1');
+                    // 验证是否为有效 JSON
+                    const parsed = JSON.parse(jsonText);
+                    const cleanJson = JSON.stringify(parsed);
+                    dataUrl = `data:application/json;base64,${Buffer.from(cleanJson).toString('base64')}`;
+                    finalSize = Buffer.from(cleanJson).length;
+                }
+                catch (error) {
+                    console.warn(`⚠️  警告: JSON 文件格式无效，使用空对象: ${asset.name || cleanUrl}`);
+                    const emptyJson = '{}';
+                    dataUrl = `data:application/json;base64,${Buffer.from(emptyJson).toString('base64')}`;
+                    finalSize = 2;
+                }
+            }
             // ✅ 核心优化：如果是图片，使用 sharp 压缩
-            if (isImageFile(cleanUrl)) {
+            else if (isImageFile(cleanUrl)) {
                 const compressed = await compressImage(buffer, cleanUrl, {
                     convertToWebP: true,
                     quality: 75,
                 });
-                dataUrl = `data:${compressed.mime};base64,${compressed.buffer.toString('base64')}`;
-                finalSize = compressed.buffer.length;
-                // 记录优化效果
-                const savings = ((1 - finalSize / originalSize) * 100).toFixed(1);
-                optimizedAssets.push(`${asset.name || assetId}: ${(originalSize / 1024).toFixed(1)}KB → ${(finalSize / 1024).toFixed(1)}KB (-${savings}%)`);
+                // 防御性检查：如果压缩后的 buffer 为空，使用原始 buffer
+                if (!compressed.buffer || compressed.buffer.length === 0) {
+                    console.warn(`⚠️  警告: 压缩后的图片为空，使用原始文件: ${asset.name || cleanUrl}`);
+                    const mime = guessMimeType(cleanUrl);
+                    dataUrl = `data:${mime};base64,${buffer.toString('base64')}`;
+                    finalSize = originalSize;
+                }
+                else {
+                    const base64 = compressed.buffer.toString('base64');
+                    // 额外检查：确保 base64 不为空
+                    if (!base64 || base64.length === 0) {
+                        console.warn(`⚠️  警告: base64 编码为空: ${asset.name || cleanUrl}`);
+                        const mime = guessMimeType(cleanUrl);
+                        dataUrl = `data:${mime};base64,${buffer.toString('base64')}`;
+                        finalSize = originalSize;
+                    }
+                    else {
+                        dataUrl = `data:${compressed.mime};base64,${base64}`;
+                        finalSize = compressed.buffer.length;
+                    }
+                    // 记录优化效果
+                    const savings = ((1 - finalSize / originalSize) * 100).toFixed(1);
+                    optimizedAssets.push(`${asset.name || assetId}: ${(originalSize / 1024).toFixed(1)}KB → ${(finalSize / 1024).toFixed(1)}KB (-${savings}%)`);
+                }
             }
             else {
                 // 非图片文件，直接 base64 编码
@@ -674,7 +1052,13 @@ async function inlineConfigAssetUrls(configJson, baseBuildDir, pluginContext) {
             }
         }
         catch (error) {
-            console.warn(`警告: 资源文件不存在: ${url}`);
+            // 记录缺失资源详情，不只是简单警告
+            missingAssets.push({
+                name: asset.name || assetId,
+                url: cleanUrl,
+                type: asset.type || 'unknown',
+                size: file.size,
+            });
         }
     }
     // 输出统计信息
@@ -702,6 +1086,40 @@ async function inlineConfigAssetUrls(configJson, baseBuildDir, pluginContext) {
             console.log(`  ... 还有 ${skippedScripts.length - 5} 个脚本`);
         }
     }
+    // ⚠️ 重要：显示缺失资源的详细警告
+    if (missingAssets.length > 0) {
+        console.log('\n');
+        console.warn(`⚠️  ==================== 缺失资源警告 ====================`);
+        console.warn(`❌ 发现 ${missingAssets.length} 个资源文件不存在！`);
+        console.warn(`   这些资源将不会被打包，可能导致游戏功能缺失！\n`);
+        // 按类型分组显示
+        const groupedByType = {};
+        for (const asset of missingAssets) {
+            const type = asset.type || 'unknown';
+            if (!groupedByType[type]) {
+                groupedByType[type] = [];
+            }
+            groupedByType[type].push(asset);
+        }
+        for (const [type, assets] of Object.entries(groupedByType)) {
+            console.warn(`   [${type}] ${assets.length} 个:`);
+            const displayCount = Math.min(assets.length, 5);
+            for (let i = 0; i < displayCount; i++) {
+                const asset = assets[i];
+                const sizeInfo = asset.size ? ` (${(asset.size / 1024).toFixed(1)}KB)` : '';
+                console.warn(`     - ${asset.name}${sizeInfo}`);
+                console.warn(`       路径: ${asset.url}`);
+            }
+            if (assets.length > 5) {
+                console.warn(`     ... 还有 ${assets.length - 5} 个 ${type} 资源`);
+            }
+        }
+        console.warn(`\n   💡 建议:`);
+        console.warn(`      1. 检查 Base Build 是否包含所有资源文件`);
+        console.warn(`      2. 确认资源路径是否正确`);
+        console.warn(`      3. 如果使用场景选择功能，确认所选场景包含所有依赖资源`);
+        console.warn(`⚠️  ======================================================\n`);
+    }
     return configJson;
 }
 async function inlineLogoInStartScript(startCode, baseBuildDir) {
@@ -715,6 +1133,30 @@ async function inlineLogoInStartScript(startCode, baseBuildDir) {
         return startCode;
     }
 }
+/**
+ * 为跳过的资源生成有效的占位符 data URL
+ */
+function getPlaceholderDataUrl(assetType, fileName) {
+    // 1x1 透明 PNG 的 base64 编码（最小有效图片）
+    const transparentPng = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
+    // JSON 类型：返回空 JSON 对象
+    if (assetType === 'json' || fileName.endsWith('.json')) {
+        return `data:application/json;base64,${Buffer.from('{}').toString('base64')}`;
+    }
+    // 图片/纹理类型：返回 1x1 透明 PNG
+    // 优先检查 assetType，因为文件名可能没有扩展名
+    if (assetType === 'texture' || assetType === 'textureatlas' || isImageFile(fileName)) {
+        return `data:image/png;base64,${transparentPng}`;
+    }
+    // 文本类型：返回单个空格的 base64
+    const mime = guessMimeType(fileName);
+    if (mime.startsWith('text/') || assetType === 'text' || assetType === 'html' || assetType === 'css') {
+        return `data:${mime};base64,${Buffer.from(' ').toString('base64')}`;
+    }
+    // 默认：对于所有其他类型，使用 1x1 透明 PNG 作为通用占位符
+    // 这对大多数二进制格式都是安全的
+    return `data:image/png;base64,${transparentPng}`;
+}
 /**
  * 判断是否为图片文件
  */
@@ -743,6 +1185,11 @@ async function compressImage(buffer, filePath, options) {
             const webpBuffer = await image
                 .webp({ quality, effort: 6 })
                 .toBuffer();
+            // 防御性检查：如果压缩后为空，返回原始 buffer
+            if (!webpBuffer || webpBuffer.length === 0) {
+                console.warn(`警告: WebP 转换后为空，使用原始格式`);
+                return { buffer, mime: guessMimeType(filePath) };
+            }
             return {
                 buffer: webpBuffer,
                 mime: 'image/webp',
@@ -754,12 +1201,22 @@ async function compressImage(buffer, filePath, options) {
                 const pngBuffer = await image
                     .png({ quality: 80, compressionLevel: 9 })
                     .toBuffer();
+                // 防御性检查
+                if (!pngBuffer || pngBuffer.length === 0) {
+                    console.warn(`警告: PNG 压缩后为空，使用原始文件`);
+                    return { buffer, mime: 'image/png' };
+                }
                 return { buffer: pngBuffer, mime: 'image/png' };
             case '.jpg':
             case '.jpeg':
                 const jpgBuffer = await image
                     .jpeg({ quality: options?.quality ?? 80, mozjpeg: true })
                     .toBuffer();
+                // 防御性检查
+                if (!jpgBuffer || jpgBuffer.length === 0) {
+                    console.warn(`警告: JPEG 压缩后为空，使用原始文件`);
+                    return { buffer, mime: 'image/jpeg' };
+                }
                 return { buffer: jpgBuffer, mime: 'image/jpeg' };
             default:
                 // 其他格式不压缩