《Cocos 游戏开发高级编程》10.2 大型项目模块化

ui ──┐
     ├──▶ game ──▶ core
platform ──┘        ▲
     └──────────────┘

// assets/scripts/core/platform/storage.ts
export interface Storage {
  read(key: string): string | null;
  write(key: string, value: string): void;
}

// 业务侧只依赖接口，不知道背后是 localStorage 还是 wx.setStorageSync
export function saveScore(storage: Storage, score: number): void {
  storage.write('blockdash.save.v1', JSON.stringify({ score }));
}

import { sys } from 'cc';
import { Storage } from '../core/platform/storage';

export class SysStorage implements Storage {
  read(key: string): string | null {
    return sys.localStorage?.getItem(key) ?? null;
  }

  write(key: string, value: string): void {
    sys.localStorage?.setItem(key, value);
  }
}

选中 assets/bundle-levels 文件夹 → 属性检查器
├── Is Bundle          ✅ 勾选
├── Bundle Name        bundle-levels
├── Priority           1
├── Compression        Merge Deps
└── Is Remote          ❌ 未勾选

// scripts/analyze/find-cycles.ts —— 纯 TypeScript，不 import 'cc'
const IMPORT_RE = /import\s[^;]*?from\s+['"]([^'"]+)['"]/g;

export function extractRelativeDeps(source: string): string[] {
  const deps: string[] = [];
  for (const match of source.matchAll(IMPORT_RE)) {
    const spec = match[1];
    if (spec.startsWith('.')) deps.push(spec);
  }
  return deps;
}

export function findCycles(graph: Map<string, string[]>): string[][] {
  const cycles: string[][] = [];
  const state = new Map<string, number>(); // 0 未访问 / 1 在栈上 / 2 已完成
  const stack: string[] = [];

  const visit = (node: string): void => {
    state.set(node, 1);
    stack.push(node);
    for (const next of graph.get(node) ?? []) {
      const s = state.get(next) ?? 0;
      if (s === 1) {
        const start = stack.indexOf(next);
        cycles.push(stack.slice(start).concat(next));
      } else if (s === 0) {
        visit(next);
      }
    }
    stack.pop();
    state.set(node, 2);
  };

  for (const node of graph.keys()) {
    if ((state.get(node) ?? 0) === 0) visit(node);
  }
  return cycles;
}

import { describe, expect, it } from 'vitest';
import { extractRelativeDeps, findCycles } from '../scripts/analyze/find-cycles';

describe('findCycles', () => {
  it('识别出 core → game → ui → core 的环', () => {
    const graph = new Map<string, string[]>([
      ['core/a.ts', ['game/b.ts']],
      ['game/b.ts', ['ui/c.ts']],
      ['ui/c.ts', ['core/a.ts']],
    ]);
    expect(findCycles(graph)).toEqual([
      ['core/a.ts', 'game/b.ts', 'ui/c.ts', 'core/a.ts'],
    ]);
  });

  it('无环图返回空数组', () => {
    const graph = new Map<string, string[]>([
      ['ui/c.ts', ['game/b.ts']],
      ['game/b.ts', ['core/a.ts']],
      ['core/a.ts', []],
    ]);
    expect(findCycles(graph)).toEqual([]);
  });

  it('只抽取相对 import', () => {
    const src = "import { Component } from 'cc';\nimport { World } from '../core/ecs/world';";
    expect(extractRelativeDeps(src)).toEqual(['../core/ecs/world']);
  });
});

import { _decorator, Component, assetManager, AssetManager, JsonAsset, warn } from 'cc';

const { ccclass } = _decorator;

@ccclass('LevelBundleLoader')
export class LevelBundleLoader extends Component {
  private bundle: AssetManager.Bundle | null = null;

  async loadLevelConfig(): Promise<JsonAsset | null> {
    const bundle = await new Promise<AssetManager.Bundle | null>((resolve) => {
      assetManager.loadBundle('bundle-levels', (err, loaded) => {
        if (err) {
          warn('[block-dash] 分包加载失败：', err.message);
          resolve(null);
          return;
        }
        resolve(loaded);
      });
    });
    if (!bundle) return null;
    this.bundle = bundle;

    return new Promise<JsonAsset | null>((resolve) => {
      bundle.load('configs/levels', JsonAsset, (err, asset) => {
        if (err) {
          warn('[block-dash] 关卡配置加载失败：', err.message);
          resolve(null);
          return;
        }
        resolve(asset);
      });
    });
  }
}