cocos/web-template/主站对接说明.md

主站 Web 对接完整步骤（Cocos tfrh001）

一、在 Cocos Creator 中构建 Web Desktop

1. 打开工程

/Users/liuyufei/tfrh/cocos/tfrh001

确认已存在 assets/scenes/main.scene，且节点上挂了 AppBootstrap。

2. 设置启动场景

项目 → 项目设置 → 项目数据 → 启动场景 → 选择 main。

3. 构建发布

1. 菜单 项目 → 构建发布（或顶部 构建 按钮）
2. 发布平台：选 Web Desktop（不要选 Web Mobile，除非只做手机）
3. 构建路径：默认 build/web-desktop（可保持默认）
4. 初始场景：main
5. 建议勾选：
   • 内联所有 SpriteFrame（减少请求数，可选）
   • MD5 Cache（按需）
6. 点击 构建
7. 构建成功后点击 运行 可先本地测一遍

4. 构建产物位置

tfrh001/build/web-desktop/
├── index.html          ← 含 Cocos 启动 script 列表
├── index.js
├── src/
│   ├── system.bundle.js
│   ├── polyfills.bundle.js
│   └── ...
├── assets/             ← 资源
└── ...

若 build/web-desktop 不存在，说明尚未在编辑器里点过「构建」。

---

二、合并到主站静态目录

方式 A：自动脚本（推荐）

在终端执行（先完成上一节构建）：

cd /Users/liuyufei/tfrh/cocos/tfrh001

# 部署到主站 Template 下（与 Unity 模板并列，便于对比）
bash tools/deploy-to-main.sh \
  --build build/web-desktop \
  --target "/Users/liuyufei/tfrh/主站文件/主站/Template/cocos"

部署后目录：

主站/Template/
├── index.html              ← 原 Unity 页（参考）
├── cocos-bridge.js         ← 新增：JS 桥
├── cocos-demo.html         ← 新增：联调页
└── cocos/                  ← Cocos 构建产物
    ├── index.html
    └── src/ ...

方式 B：手动复制

复制源	复制到
build/web-desktop/*	主站静态目录下的 cocos/
web-template/cocos-bridge.js	与主站 index.html 同级

---

三、修改主站 index.html

1. 引入 cocos-bridge（在 Unity 脚本之前）

<script src="cocos-bridge.js"></script>

cocos-bridge.js 会注册：

• processData / processVehicleData / externalResult / externalLevelInfo / coinsData
• 等待 window.unityInstance 就绪

2. 删除 Unity 加载段

删除类似内容：

<script src="Build/build.loader.js"></script>
<script>
  createUnityInstance(canvas, config, ...).then((unityInstance) => {
    window.unityInstance = unityInstance;
  });
</script>

3. 粘贴 Cocos 启动脚本

构建完成后运行（自动生成粘贴清单）：

node tools/patch-main-index.js build/web-desktop

将输出的 <script src="cocos/..."> 按主站实际路径写入 index.html。

路径规则：

• 主站页面与 cocos/ 同级 → src="cocos/src/system.bundle.js"
• 游戏在根目录 → 不加 cocos/ 前缀

4. 游戏容器

保留或添加 Cocos 构建页中的结构：

<div id="GameDiv">
  <div id="Cocos3dGameContainer">
    <canvas id="GameCanvas"></canvas>
  </div>
</div>

若主站原用 #unity-canvas，可只改 id 为 GameCanvas，或保留原 id 并在构建模板里改 canvas id（需改构建配置，一般直接用 Cocos 默认即可）。

5. unityInstance 无需手写

游戏启动后 GameController 会自动执行：

window.unityInstance = { SendMessage: ... };
window.cocosIns = 同上;

主站 Blockly 代码 不用改：

unityInstance.SendMessage("Player", "CallMove", n);
unityInstance.SendMessage("GameController", "SwitchLevel", levelId);

---

四、本地预览

仅预览 Cocos 构建（未合并主站）

用 Cocos 构建面板里的 运行，或：

cd build/web-desktop
npx --yes serve . -p 8080
# 打开 http://localhost:8080

预览合并后的主站目录

cd "/Users/liuyufei/tfrh/主站文件/主站/Template"
npx --yes serve . -p 8080

• 联调页：http://localhost:8080/cocos-demo.html
• 若已改主站 index：http://localhost:8080/index.html

---

五、联调自检清单

步骤	期望
打开页面	控制台无 404（检查 cocos/*.js 路径）
加载完成	[GameController] unityInstance.SendMessage 已就绪
	[tfrh] Cocos bridge ready
SwitchLevel(1)	日志 externalLevelInfo
CallMove(2)	角色移动
CallPlayerInfo	日志 processData

---

六、CDN 整包发布（对标 Unity mstest5）

与 Unity 把 mstest5/ 整目录上传 CDN 一样，Cocos 也支持单目录静态部署，无需 Node 服务器。

1. 构建 + 打 CDN 包（与 Unity 参考包文件树 100% 一致）

参考 Unity 包：/Users/liuyufei/tfrh/竞赛/mstest5

cd /Users/liuyufei/tfrh/cocos/tfrh001

# ① Cocos Creator：项目 → 构建发布 → Web Desktop → 构建
# ② 打成与 Unity 完全相同的目录/文件名
bash tools/package-for-cdn.sh --build build/web-desktop-001

# 输出到竞赛目录旁（便于对比）
bash tools/package-for-cdn.sh --build build/web-desktop-001 --out "/Users/liuyufei/tfrh/竞赛/mstest5-cocos"

2. 产物结构（与 Unity 参考逐文件对齐）

mstest5/
├── index.html
├── Build/
│   ├── mstest5.loader.js
│   ├── mstest5.data.br
│   ├── mstest5.framework.js.br
│   └── mstest5.wasm.br
├── StreamingAssets/aa/
│   ├── catalog.json
│   ├── settings.json
│   ├── AddressablesLink/link.xml
│   └── WebGL/
│       ├── 3a39a2f..._unitybuiltinshaders_....bundle
│       ├── defaultlocalgroup_assets_all_1baf4413....bundle  ← Cocos 资源 zip
│       └── defaultlocalgroup_scenes_all_44c83ead....bundle ← Cocos 引擎 zip
└── TemplateData/（11 个文件，与 Unity 相同）

index.html / TemplateData / catalog.json / settings.json / link.xml / unitybuiltinshaders.bundle 直接复制 Unity 参考包；Cocos 运行时打进两个 defaultlocalgroup_*.bundle，由自定义 mstest5.loader.js 解压并启动。

3. 上传与访问

1. 将 mstest5/ 内全部文件上传到 CDN 的 mstest5 目录（覆盖原 Unity 包）
2. 浏览器打开 https://你的CDN域名/mstest5/index.html
3. 主站 iframe 嵌入（URL 与 Unity 时代相同，只换引擎）：

<iframe src="https://cdn.example.com/mstest5/index.html" width="960" height="600"></iframe>

4. 构建面板建议（CDN 场景）

选项	建议
发布平台	Web Desktop
资源服务器地址 server	留空（资源与页面同域相对路径加载）
MD5 Cache	生产可开启，更新后需刷新 CDN 缓存
主包压缩	默认 merge_dep 即可

若资源与页面不在同一路径，在构建面板填写 CDN 根 URL 到「资源服务器地址」，例如 https://cdn.example.com/tfrh001/。

5. 与 Unity mstest5 对比

	Unity mstest5	Cocos mstest5
入口	index.html	index.html
运行时	Build/*.br (WASM)	cocos-js/ + src/ (JS)
关卡资源	StreamingAssets/aa/*.bundle	assets/ (JSON + 贴图)
JS 桥	需主站页挂回调	已含 cocos-bridge.js
Brotli	需要 Content-Encoding: br	普通静态文件即可

---

七、生产环境注意

1. HTTPS：与 Unity 相同，WebGL/Canvas 在混合内容下可能受限
2. 缓存：构建带 MD5 时，更新后清 CDN 缓存
3. 跨域：cocos/ 与主站同域部署最省事
4. 回退：可保留 Unity Build/ 目录，通过配置开关切换加载 Unity 或 Cocos

---

八、关卡

已导入 Levels600 共 600 关，SwitchLevel(1..600) 与 Unity 一致。