@playcraft/build 0.0.8 → 0.0.10

package/README.md

@@ -1,13 +1,129 @@
 # @playcraft/build
 
-PlayCraft 核心构建模块。将 PlayCanvas/PlayCraft 项目打包为 Playable Ads。
+PlayCraft 构建系统核心包，提供 Playable Ads 的构建、打包和优化功能。
 
-## 功能
+## 功能特性
 
-- 两阶段构建（Base Build → Channel Build）
-- 支持 10 个广告平台
-- 使用 Vite 进行资源内联与压缩
-- 平台特定适配与 SDK 注入
+### 🎯 核心功能
+
+- **多平台支持**：支持 10+ 主流广告平台（Facebook、Snapchat、ironSource 等）
+- **场景过滤**：智能分析场景依赖，只打包选中场景使用的资源
+- **资源优化**：自动精简资源元数据，显著减少 config.json 体积
+- **两阶段构建**：基础构建 + 渠道适配，灵活高效
+
+### 📦 config.json 优化
+
+`config.json` 是 PlayCanvas 项目的核心配置文件，包含所有资源的元数据。在大型项目中，这个文件可能达到 2MB 甚至更大，严重影响 Playable Ads 的加载性能。
+
+#### 优化策略
+
+**1. 资源元数据精简（默认启用）**
+
+自动删除运行时不需要的字段，包括：
+- `tags` - 编辑器标签
+- `i18n` - 国际化数据
+- `meta` - 编辑器元数据
+- `thumbnails` - 缩略图
+- `revision` - 版本号
+- `created_at` / `updated_at` - 时间戳
+- `user` / `branch_id` - 用户和分支信息
+
+**预期效果**：减少 30-50% 的 config.json 体积
+
+**2. 场景依赖分析**
+
+结合场景过滤功能，只包含选中场景实际使用的资源。
+
+**预期效果**：减少 40-70% 的资源数量
+
+**3. 组合优化**
+
+同时启用元数据精简和场景过滤，可以实现最佳优化效果。
+
+**预期效果**：总体减少 60-80% 的 config.json 体积
+
+#### 使用方式
+
+```typescript
+import { generateConfig } from '@playcraft/build';
+
+// 默认启用元数据精简
+const config = await generateConfig(projectConfig, {
+  selectedScenes: ['MainScene'],  // 场景过滤
+  projectDir: './project',
+  stripMetadata: true,  // 元数据精简（默认 true）
+});
+
+// 禁用元数据精简（保留完整元数据）
+const configFull = await generateConfig(projectConfig, {
+  stripMetadata: false,
+});
+```
+
+#### 优化效果示例
+
+```
+🗜️  元数据精简统计:
+  - 原始大小: 2048.5 KB
+  - 精简后: 1024.3 KB
+  - 节省: 1024.2 KB (50.0%)
+
+📊 资源过滤统计:
+  - 总资源数: 450
+  - 场景依赖: 180
+  - 将节省: 270 个资源 (60.0%)
+```
+
+#### 运行时兼容性
+
+精简后的 config.json 完全兼容 PlayCanvas 引擎，所有运行时需要的字段都会保留：
+
+- ✅ 资源 URL 和文件信息
+- ✅ 纹理过滤和寻址模式
+- ✅ 材质配置
+- ✅ 模型映射信息
+- ✅ 脚本加载配置
+- ✅ 动画和音频时长
+- ✅ 字体和精灵配置
+
+#### 高级优化方案
+
+如果需要进一步优化，可以考虑：
+
+**方案二：数据压缩**
+- 使用 lz4/gzip 压缩 config.json
+- 运行时解压
+- 预期减少 60-70% 体积
+
+**方案三：按需加载**
+- 只在 config.json 中保留资源引用
+- 详细元数据按需加载
+- 预期减少 70-80% 体积
+
+## API 文档
+
+### generateConfig(projectConfig, options?)
+
+生成 PlayCanvas 构建产物格式的 config.json。
+
+**参数**：
+- `projectConfig`: PlayCanvasProject | PlayCraftProject - 项目配置
+- `options`: GenerateConfigOptions - 可选配置
+  - `selectedScenes?: string[]` - 选中的场景 ID 或名称列表
+  - `projectDir?: string` - 项目目录（用于加载完整场景文件）
+  - `stripMetadata?: boolean` - 是否精简资源元数据（默认 true）
+
+**返回值**：Promise<any> - config.json 对象
+
+## 相关文档
+
+- [构建架构设计](../../docs/cli/build-architecture.md)
+- [平台规格对照表](../../docs/cli/各渠道Playable规格对照表.md)
+- [优化对照](../../docs/cli/playable-ads-optimization.md)
+
+## License
+
+MIT
 
 ## 支持的平台
 

package/dist/analyzers/__tests__/optimization-analyzer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/analyzers/__tests__/optimization-analyzer.test.js

@@ -0,0 +1,169 @@
+import { describe, it, expect } from 'vitest';
+import { OptimizationAnalyzer } from '../optimization-analyzer.js';
+describe('OptimizationAnalyzer', () => {
+    it('should detect large uncompressed files', () => {
+        const state = {
+            version: '1.0.0',
+            buildTime: Date.now(),
+            assets: {
+                'large-file': {
+                    id: 'large-file',
+                    originalName: 'large-file.js',
+                    originalPath: '/path/to/large-file.js',
+                    originalSize: 200 * 1024, // 200KB
+                    finalSize: 195 * 1024, // 只压缩了 5KB
+                    totalCompressionRatio: 0.025, // 2.5% 压缩率
+                    type: 'script',
+                    processingHistory: [
+                        {
+                            stage: 'base-build',
+                            name: 'large-file.js',
+                            size: 195 * 1024,
+                            optimizations: [],
+                        },
+                    ],
+                },
+            },
+            stages: [],
+        };
+        const analyzer = new OptimizationAnalyzer(state);
+        const result = analyzer.analyze();
+        expect(result.totalSuggestions).toBeGreaterThan(0);
+        expect(result.suggestions.some(s => s.type === 'large-uncompressed')).toBe(true);
+    });
+    it('should detect PNG images that can be converted to WebP', () => {
+        const state = {
+            version: '1.0.0',
+            buildTime: Date.now(),
+            assets: {
+                'image': {
+                    id: 'image',
+                    originalName: 'image.png',
+                    originalPath: '/path/to/image.png',
+                    originalSize: 100 * 1024, // 100KB
+                    finalSize: 100 * 1024,
+                    totalCompressionRatio: 0,
+                    type: 'texture',
+                    processingHistory: [
+                        {
+                            stage: 'base-build',
+                            name: 'image.png',
+                            size: 100 * 1024,
+                            optimizations: [],
+                        },
+                    ],
+                },
+            },
+            stages: [],
+        };
+        const analyzer = new OptimizationAnalyzer(state);
+        const result = analyzer.analyze();
+        expect(result.suggestions.some(s => s.type === 'format-conversion')).toBe(true);
+    });
+    it('should detect missing minification', () => {
+        const state = {
+            version: '1.0.0',
+            buildTime: Date.now(),
+            assets: {
+                'script': {
+                    id: 'script',
+                    originalName: 'script.js',
+                    originalPath: '/path/to/script.js',
+                    originalSize: 50 * 1024, // 50KB
+                    finalSize: 50 * 1024,
+                    totalCompressionRatio: 0,
+                    type: 'script',
+                    processingHistory: [
+                        {
+                            stage: 'base-build',
+                            name: 'script.js',
+                            size: 50 * 1024,
+                            optimizations: [], // 没有 minify
+                        },
+                    ],
+                },
+            },
+            stages: [],
+        };
+        const analyzer = new OptimizationAnalyzer(state);
+        const result = analyzer.analyze();
+        expect(result.suggestions.some(s => s.type === 'enable-minify')).toBe(true);
+    });
+    it('should group suggestions by severity', () => {
+        const state = {
+            version: '1.0.0',
+            buildTime: Date.now(),
+            assets: {
+                'large-uncompressed': {
+                    id: 'large-uncompressed',
+                    originalName: 'large.js',
+                    originalPath: '/path/to/large.js',
+                    originalSize: 200 * 1024,
+                    finalSize: 195 * 1024,
+                    totalCompressionRatio: 0.025,
+                    type: 'script',
+                    processingHistory: [
+                        {
+                            stage: 'base-build',
+                            name: 'large.js',
+                            size: 195 * 1024,
+                            optimizations: [],
+                        },
+                    ],
+                },
+                'png-image': {
+                    id: 'png-image',
+                    originalName: 'image.png',
+                    originalPath: '/path/to/image.png',
+                    originalSize: 100 * 1024,
+                    finalSize: 100 * 1024,
+                    totalCompressionRatio: 0,
+                    type: 'texture',
+                    processingHistory: [
+                        {
+                            stage: 'base-build',
+                            name: 'image.png',
+                            size: 100 * 1024,
+                            optimizations: [],
+                        },
+                    ],
+                },
+            },
+            stages: [],
+        };
+        const analyzer = new OptimizationAnalyzer(state);
+        const result = analyzer.analyze();
+        expect(result.bySeverity.high.length).toBeGreaterThan(0);
+        expect(result.bySeverity.medium.length).toBeGreaterThan(0);
+    });
+    it('should calculate total estimated savings', () => {
+        const state = {
+            version: '1.0.0',
+            buildTime: Date.now(),
+            assets: {
+                'large-file': {
+                    id: 'large-file',
+                    originalName: 'large-file.js',
+                    originalPath: '/path/to/large-file.js',
+                    originalSize: 200 * 1024,
+                    finalSize: 195 * 1024,
+                    totalCompressionRatio: 0.025,
+                    type: 'script',
+                    processingHistory: [
+                        {
+                            stage: 'base-build',
+                            name: 'large-file.js',
+                            size: 195 * 1024,
+                            optimizations: [],
+                        },
+                    ],
+                },
+            },
+            stages: [],
+        };
+        const analyzer = new OptimizationAnalyzer(state);
+        const result = analyzer.analyze();
+        expect(result.totalEstimatedSavings).toBeGreaterThan(0);
+        expect(result.estimatedOptimizationRate).toBeGreaterThan(0);
+    });
+});

package/dist/analyzers/build-analyzer.d.ts

@@ -0,0 +1,98 @@
+export interface FileAnalysis {
+    path: string;
+    relativePath: string;
+    size: number;
+    sizeFormatted: string;
+    dataUrlSize: number;
+    dataUrlSizeFormatted: string;
+    type: string;
+    category: string;
+}
+export interface BuildAnalysisReport {
+    totalFiles: number;
+    totalSize: number;
+    totalSizeFormatted: string;
+    estimatedHtmlSize: number;
+    estimatedHtmlSizeFormatted: string;
+    files: FileAnalysis[];
+    byCategory: Record<string, {
+        count: number;
+        size: number;
+        sizeFormatted: string;
+        dataUrlSize: number;
+        dataUrlSizeFormatted: string;
+    }>;
+    byType: Record<string, {
+        count: number;
+        size: number;
+        sizeFormatted: string;
+    }>;
+}
+/**
+ * 构建分析器 - 分析构建产物并生成详细报告
+ */
+export declare class BuildAnalyzer {
+    private buildDir;
+    private outputDir;
+    constructor(buildDir: string, outputDir: string);
+    /**
+     * 分析构建产物
+     */
+    analyze(): Promise<BuildAnalysisReport>;
+    /**
+     * 从 build-state.json 分析
+     */
+    private analyzeFromState;
+    /**
+     * 从文件系统分析（回退方案）
+     */
+    private analyzeFromFileSystem;
+    /**
+     * 估算 data URL 大小
+     */
+    private estimateDataUrlSize;
+    /**
+     * 映射资产类型到文件类型
+     */
+    private mapAssetTypeToFileType;
+    /**
+     * 映射资产类型到分类
+     */
+    private mapAssetTypeToCategory;
+    /**
+     * 生成 HTML 报告
+     */
+    generateHTMLReport(report: BuildAnalysisReport): Promise<string>;
+    /**
+     * 扫描目录获取所有文件
+     */
+    private scanDirectory;
+    /**
+     * 分析单个文件
+     */
+    private analyzeFile;
+    /**
+     * 获取文件类型
+     */
+    private getFileType;
+    /**
+     * 获取文件分类
+     */
+    private getFileCategory;
+    /**
+     * 获取 data URL 前缀
+     */
+    private getDataUrlPrefix;
+    /**
+     * 格式化文件大小
+     */
+    private formatSize;
+    /**
+     * 生成树状图数据结构
+     */
+    private generateTreemapData;
+    /**
+     * 生成 HTML 报告内容
+     */
+    private generateReportHTML;
+}