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

---

六、生产环境注意

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

---

七、关卡

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