《Cocos 游戏开发入门》17.1 构建流程与产物体积分析

dist/
├── index.html                    # 入口，只引一个带哈希的 JS
└── assets/
    ├── index-4f2a9c.js           # 业务入口
    ├── engine-1c8b70.js          # manualChunks 拆出的引擎 chunk
    ├── gameplay-9d3e12.js        # 玩法 chunk
    ├── boss-level-77a1f0.js      # 动态 import 切出的懒加载 chunk
    ├── index-2b6d41.css          # 样式（cssCodeSplit 关闭后只有一个）
    ├── blocks-8a1e3f.png         # 大图，超过内联阈值，独立成文件
    └── icon-tiny-3c9d2a.svg      # 小图标，若小于 4KB 会被内联，不在此列出

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  // 相对路径，便于产物放到任意子目录或 CDN 路径下
  base: './',
  build: {
    target: 'es2020',
    outDir: 'dist',
    // 小于 4KB 的资源内联成 base64，省一次 HTTP 请求
    assetsInlineLimit: 4096,
    // 关闭 CSS 代码拆分，样式全部打进一个 css 文件
    cssCodeSplit: false,
    sourcemap: false,
    rollupOptions: {
      output: {
        entryFileNames: 'assets/[name]-[hash].js',
        chunkFileNames: 'assets/[name]-[hash].js',
        assetFileNames: 'assets/[name]-[hash][extname]',
        // 把体积大、变动少的模块拆成独立 chunk，利于缓存复用
        manualChunks: {
          engine: ['./src/core/loop.ts', './src/core/scene.ts'],
          gameplay: ['./src/game/levels.ts', './src/game/loot.ts'],
        },
      },
    },
  },
});

// 动态 import 让 Rollup 自动切出一个独立 chunk，按需下载
export async function enterBossLevel(): Promise<void> {
  const mod = await import('./boss-level');
  mod.start();
}

// scripts/analyze-dist.ts
import { readdirSync, statSync, readFileSync } from 'node:fs';
import { join, extname } from 'node:path';
import { gzipSync } from 'node:zlib';

function walk(dir: string, out: string[] = []): string[] {
  for (const name of readdirSync(dir)) {
    const full = join(dir, name);
    if (statSync(full).isDirectory()) walk(full, out);
    else out.push(full);
  }
  return out;
}

// 扩展名到类别的映射，未命中的归入 other
const CATEGORY: Record<string, string> = {
  '.js': 'code',
  '.css': 'code',
  '.png': 'image',
  '.jpg': 'image',
  '.webp': 'image',
  '.mp3': 'audio',
  '.ogg': 'audio',
  '.json': 'data',
  '.atlas': 'data',
};

function categorize(file: string): string {
  return CATEGORY[extname(file).toLowerCase()] ?? 'other';
}

interface Totals {
  raw: number;
  gzip: number;
}

const groups = new Map<string, Totals>();
let grand: Totals = { raw: 0, gzip: 0 };

for (const path of walk('dist')) {
  const buf = readFileSync(path);
  const gz = gzipSync(buf).length;
  const key = categorize(path);
  const acc = groups.get(key) ?? { raw: 0, gzip: 0 };
  acc.raw += buf.length;
  acc.gzip += gz;
  groups.set(key, acc);
  grand.raw += buf.length;
  grand.gzip += gz;
}

// 按原始体积从大到小排列，最占地方的一眼可见
const rows = [...groups.entries()].sort((a, b) => b[1].raw - a[1].raw);
const kb = (n: number): string => `${(n / 1024).toFixed(1)} KB`;

for (const [name, t] of rows) {
  const share = ((t.raw / grand.raw) * 100).toFixed(1);
  console.log(`${name.padEnd(6)} ${kb(t.raw).padStart(10)}  gzip ${kb(t.gzip).padStart(10)}  ${share}%`);
}
console.log(`total  ${kb(grand.raw).padStart(10)}  gzip ${kb(grand.gzip).padStart(10)}`);

// 一行验证：同一份 JS，gzip 后大概缩到几成
const raw = readFileSync('dist/assets/main-8f3a1c.js');
const gz = gzipSync(raw);
console.log(`raw ${raw.length} -> gzip ${gz.length} (${((gz.length / raw.length) * 100).toFixed(1)}%)`);

// scripts/analyze-dist.ts 末尾追加
const BUDGET_KB: Record<string, number> = {
  code: 200,   // gzip 后
  data: 80,
  image: 2600,
  audio: 1000,
};

let failed = false;
for (const [name, limitKb] of Object.entries(BUDGET_KB)) {
  const usedKb = (groups.get(name)?.gzip ?? 0) / 1024;
  if (usedKb > limitKb) {
    console.error(`[budget] ${name} 超标：${usedKb.toFixed(1)} KB > ${limitKb} KB`);
    failed = true;
  }
}
if (failed) process.exit(1);

npm run build
node scripts/analyze-dist.ts   # 超标则 exit 1，流水线变红

// scripts/analyze-dist.test.ts
import { describe, expect, it } from 'vitest';

// 把「按扩展名归类」与「按类别汇总」抽成纯函数
function categorize(ext: string): string {
  const map: Record<string, string> = { '.js': 'code', '.css': 'code', '.png': 'image' };
  return map[ext.toLowerCase()] ?? 'other';
}

function sumByCategory(entries: Array<{ ext: string; size: number }>): Record<string, number> {
  const out: Record<string, number> = {};
  for (const e of entries) {
    const key = categorize(e.ext);
    out[key] = (out[key] ?? 0) + e.size;
  }
  return out;
}

describe('体积归类', () => {
  it('未知扩展名归入 other', () => {
    expect(categorize('.wasm')).toBe('other');
  });

  it('大小写不敏感', () => {
    expect(categorize('.PNG')).toBe('image');
  });

  it('按类别正确汇总', () => {
    const total = sumByCategory([
      { ext: '.js', size: 100 },
      { ext: '.css', size: 50 },
      { ext: '.png', size: 300 },
      { ext: '.wasm', size: 20 },
    ]);
    expect(total).toEqual({ code: 150, image: 300, other: 20 });
  });
});