《游戏引擎实现原理》8.2 构建与部署

// file: tools/build-prod.mjs
// tier: L1
// verify: node tools/build-prod.mjs
//
// helio《微光岛》生产构建：vite 打包（minify + 内容哈希）+ 静态资源拷贝 +
// index.html 生成 + dist/manifest.json（每文件 sha256 与字节数）。
// 本机可跑的是「构建产物」；上传到 CDN / 静态托管是 L4，见正文标注。
import { build } from 'vite';
import { createHash } from 'node:crypto';
import { mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync, cpSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { dirname, join, relative } from 'node:path';

const ROOT = fileURLToPath(new URL('..', import.meta.url));
const DIST = join(ROOT, 'dist');
const ENTRY = join(ROOT, 'src/apps/glimmer-isle-demo.ts');

rmSync(DIST, { recursive: true, force: true });
mkdirSync(DIST, { recursive: true });

// 1) 打包 JS：minify + [name]-[hash] 内容寻址。
const result = await build({
  root: ROOT, logLevel: 'error',
  build: { outDir: DIST, emptyOutDir: false, minify: true,
    rollupOptions: { input: ENTRY,
      output: { entryFileNames: 'assets/[name]-[hash].js', format: 'es' } } },
});
const out = Array.isArray(result) ? result[0] : result;
const entryName = out.output.find((c) => c.type === 'chunk' && c.isEntry)?.fileName;
if (!entryName) throw new Error('no entry chunk emitted');

// 2) 拷贝静态资源：WGSL 着色器。
cpSync(join(ROOT, 'shaders'), join(DIST, 'shaders'), { recursive: true, dereference: true });

// 3) 生成 index.html：只引用带哈希的入口，浏览器可长缓存。
writeFileSync(join(DIST, 'index.html'),
  `<!doctype html>\n<meta charset="utf-8">\n<title>微光岛 glimmer-isle</title>\n` +
  `<canvas id="app" width="960" height="540"></canvas>\n` +
  `<script type="module" src="/${entryName}"></script>\n`, 'utf8');

// 4) 清单：递归遍历 dist，对每个文件算 sha256。
const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
const walk = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
  e.isDirectory() ? walk(join(dir, e.name)) : [join(dir, e.name)]);
const files = {};
let total = 0;
for (const abs of walk(DIST).sort()) {
  const buf = readFileSync(abs);
  const rel = relative(DIST, abs).split('\\').join('/');
  files[rel] = { bytes: buf.byteLength, sha256: sha256(buf) };
  total += buf.byteLength;
}
writeFileSync(join(DIST, 'manifest.json'),
  JSON.stringify({ entry: entryName, files, totalBytes: total }, null, 2), 'utf8');

console.log(`entry: ${entryName}`);
for (const [rel, m] of Object.entries(files)) {
  console.log(`  ${rel.padEnd(46)} ${String(m.bytes).padStart(7)} B  ${m.sha256.slice(0, 12)}`);
}
console.log(`files=${Object.keys(files).length} total=${total} B`);
console.log('=== build-prod: dist/ 就绪 ===');

// file: tools/verify-dist.mjs
// tier: L1
// verify: node tools/verify-dist.mjs
//
// 校验 dist/ 与 manifest.json 是否自洽：逐个文件重算 sha256 与字节数，
// 检查 index.html 引用的入口存在，且 dist 中没有未登记的文件。
// 这是「产物可信」的本地门禁，真实 CDN 上传（L4）不在此覆盖。
import { createHash } from 'node:crypto';
import { readdirSync, readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { join, relative } from 'node:path';

const DIST = join(fileURLToPath(new URL('..', import.meta.url)), 'dist');
const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
const walk = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
  e.isDirectory() ? walk(join(dir, e.name)) : [join(dir, e.name)]);

const manifest = JSON.parse(readFileSync(join(DIST, 'manifest.json'), 'utf8'));
let fail = 0;
const bad = (msg) => { console.log(`FAIL  ${msg}`); fail++; };

for (const [rel, m] of Object.entries(manifest.files)) {
  const buf = readFileSync(join(DIST, rel));
  if (buf.byteLength !== m.bytes) bad(`${rel} 字节不符 manifest=${m.bytes} disk=${buf.byteLength}`);
  else if (sha256(buf) !== m.sha256) bad(`${rel} sha256 不符`);
}

// dist 中每个文件都必须登记（防止漏打包的残留产物）
const onDisk = new Set(walk(DIST).map((p) => relative(DIST, p).split('\\').join('/')));
for (const rel of onDisk) if (rel !== 'manifest.json' && !(rel in manifest.files)) bad(`未登记文件 ${rel}`);

// index.html 引用的入口必须存在
const html = readFileSync(join(DIST, 'index.html'), 'utf8');
const ref = html.match(/src="\/([^"]+)"/)?.[1];
if (!ref) bad('index.html 未引用任何入口');
else if (!onDisk.has(ref)) bad(`index.html 引用的 ${ref} 不存在`);
else if (ref !== manifest.entry) bad(`入口与 manifest.entry 不符：${ref} vs ${manifest.entry}`);

console.log(`checked=${Object.keys(manifest.files).length} files, total=${manifest.totalBytes} B`);
console.log(fail === 0 ? '=== verify-dist: ALL PASS ===' : `=== verify-dist: ${fail} FAILED ===`);
process.exit(fail === 0 ? 0 : 1);

[glimmer-isle] frames=120 step=0.016666666666666666 speed=2
[glimmer-isle] run A: x=9.71445146547012e-17 z=2.666666666666667 checksum=5142.666666666668
[glimmer-isle] run B: x=9.71445146547012e-17 z=2.666666666666667 checksum=5142.666666666668
[glimmer-isle] deterministic: x=true z=true checksum=true
[glimmer-isle] PASS: 两次运行逐位相同

// file: tools/serve-dist.mjs
// tier: L1
// verify: node tools/serve-dist.mjs
//
// 本地静态服务冒烟：起一个 loopback http 服务，用 fetch 取回 dist/ 的
// index.html 与清单里的入口 JS，证明产物可被 HTTP 提供。
// 仅本机验证，不对外；真实 CDN 上传是 L4。
import http from 'node:http';
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { join } from 'node:path';

const DIST = join(fileURLToPath(new URL('..', import.meta.url)), 'dist');
const srv = http.createServer((req, res) => {
  const p = req.url === '/' ? '/index.html' : req.url;
  try { res.end(readFileSync(join(DIST, p))); }
  catch { res.statusCode = 404; res.end('nf'); }
});
await new Promise((r) => srv.listen(0, '127.0.0.1', r));
const port = srv.address().port;
const entry = JSON.parse(readFileSync(join(DIST, 'manifest.json'), 'utf8')).entry;
for (const p of ['/', '/index.html', `/${entry}`]) {
  const r = await fetch(`http://127.0.0.1:${port}${p}`);
  console.log(`${p.padEnd(46)} ${r.status}  ${(await r.text()).length} chars`);
}
srv.close();
console.log('=== serve-dist: 产物可被 HTTP 提供 ===');