AIGame/Doc/WeChat_Export.md

# 微信小游戏导出、导入与首包 CDN

## 开发者工具入口

导出菜单为 `AIGame/WeChat/Export Base Package`，输出到 `AIClient/Build/WeChat/Base/`。

- `minigame/` 是开发者工具项目，包含 `game.js`、`game.json`。
- `webgl/` 是网站资源目录。打开它或父目录时若没有正确配置源码路径，会出现找不到 `game.json`。
- 导出后现在同时生成父目录 `project.config.json`，指定 `miniprogramRoot: "minigame/"`；因此可以打开 Base 或 minigame。
- 父目录入口沿用 SDK 编译配置及符号文件排除规则，保留已有 AppID；不改私有配置。
- `AIGame/WeChat/Open Exported MiniGame Folder` 定位正确的项目目录；旧包可以执行 `Repair Exported DevTools Project`。

## 启动资源下载 404

当前首包 CDN 为 `https://www.xworld.ren/game/Friends/webgl/`，与生产热更新目录位于同一个网站目录。
导出菜单会通过 Unity API 写入 MiniGameConfig 的 CDN，并由 SDK 写入 `minigame/game.js` 的 `DATA_CDN`。
修改现有包配置可用 `AIGame/WeChat/Refresh Exported Config (No Build)`，无需重新编译 Player。

**导出只生成本地文件，不会自动上传网站；重新生成底包不等于必须重新上传全部资源。** 首次部署或缺少文件时，将 `AIClient/Build/WeChat/Base/webgl/` 中需要的资源上传到网站 `/game/Friends/webgl/`，保持相对路径，不要额外嵌套一层 webgl。

| 本地相对 webgl 的路径 | 对外 URL 路径 |
| --- | --- |
| `<hash>.webgl.data.unityweb.bin.txt` | `/game/Friends/webgl/<hash>.webgl.data.unityweb.bin.txt` |
| `StreamingAssets/cdn/version.json` | `/game/Friends/webgl/StreamingAssets/cdn/version.json` |
| `StreamingAssets/yoo/...` | `/game/Friends/webgl/StreamingAssets/yoo/...` |

`base-package-report.txt` 会列出本次实际首包文件和完整下载地址。
2026-10-22 的包为 `1ddb5fcad4415dd3.webgl.data.unityweb.bin.txt`，10,084,442 字节；排查时对应生产 URL 返回 404，而现有 `/game/Friends/webgl/cdn/version.json` 返回 200。
SDK 根据 Unity data 文件内容计算哈希，并写入文件名和 `game.js` 的 `DATA_FILE_MD5`。重新构建后，如果哈希未变且现有 CDN 的完整 URL 可访问，直接复用，无需重复上传；哈希变化时才需要补充对应的新文件。未变的 YooAsset 业务资源包同样无需重复上传。场景或壳内资源／构建设置变化可能影响 Unity data，不能仅凭业务资源未修改就判断其哈希一定不变。

排查 404 时，先核对 `DATA_CDN` 与既有文件部署位置，再核对 `DATA_FILE_MD5` 对应的文件是否存在。404 本身不能证明资源内容发生了变化。修正路径或补齐缺失文件后，确认完整 URL 返回 200，再清理开发者工具缓存并编译。

Unity 首包的 `DATA_CDN` 与游戏进入 Boot 后使用的 YooAsset `version.json`／Art／DefaultPackage 是两阶段下载。当前 YooAsset 生产清单地址仍为 `/game/Friends/webgl/cdn/version.json`，资源根为 `/game/Friends/webgl/yoo/DefaultPackage`。

## 验证

`AIClient/AgentScripts/VerifyWeChatExport.cs` 通过 Unity Pipeline 刷新并验证现有包配置，检查父目录入口、AppID、SDK 排除规则、私有配置与 webgl 资源保留、重复刷新幂等性。
回执及修改前备份在 `Tools/output/wechat_export/`。本次本地验证通过，服务器首包文件尚需发布。

## YooAsset 默认构造函数被裁剪

2026-10-22 小游戏启动出现 `MissingMethodException: Default constructor not found for type YooAsset.WebNetworkFileSystem`。
YooAsset 3.0.6 的 `FileSystemParameters.CreateFileSystem` 使用 `Type.GetType` 和 `Activator.CreateInstance` 创建实例。
实际检查完整与 WebGL ManagedStripped 程序集，确认 WebNetwork／Builtin／Sandbox 三种文件系统在完整程序集中有默认构造函数，裁剪后类型仍存在、默认构造函数已移除。

`AIClient/Assets/AOT/link.xml` 仅保留项目使用的这三个文件系统的无参构造函数，不全量保留 YooAsset，也不降低全局裁剪级别。
该文件独立于 `Assets/HybridCLRGenerate/link.xml`，后续 HybridCLR Gen All 不会覆盖它。Unity 保留规则见[官方托管代码裁剪说明](https://docs.unity3d.com/cn/2022.3/Manual/ManagedCodeStripping.html)。

`AIClient/AgentScripts/VerifyYooAssetStripping.cs`：`Before` 记录裁剪前后构造函数；`BuildAndVerify` 执行正式 Export Base Package，检查新裁剪 DLL 中的构造函数及方法体、新生成的原生构造函数，并对比业务 bundle 与启动 data 的内容哈希。
回执目录为 `Tools/output/yooasset_stripping/`。底包构造函数修复需要新的 wasm 代码生效；未改动的业务资源包继续复用。

本次 20:06 正式导出与产物检查通过：三种文件系统无参构造函数及方法体均已保留，IL2CPP 已生成 WebNetworkFileSystem 构造函数；业务 bundle 内容哈希全部未变。启动 data 实测由 10,084,442 字节变为 10,084,535 字节，文件名变为 `c58ae17711192f12.webgl.data.unityweb.bin.txt`；需要将这个新增启动文件同步到现有 `/game/Friends/webgl/`，无需重传未变业务 bundle。未自动发布服务器，微信开发者工具运行尚待复测。

## 主界面移动端修复产物（2026-10-22 20:49）

启动不再自动加载 测试场景/CaoCao。主界面角色预览材质通过 Prefab 依赖进入 Art，顶部和底部布局使用设备／微信安全区，详见 `UI_AutoGen_Overview.md`。
三个屏幕布局与按钮命中、GPU 抠底、实际启动器无 3D 预加载检查通过；8 组微信窗口／胶囊／旧接口／DPR 用例通过。原 Boot 场景已恢复。

新底包已导出到 `AIClient/Build/WeChat/Base/minigame/`，构建成功并确认原生／JS 安全区桥接均包含。新首包为 `e33b1380f2e627d5.webgl.data.unityweb.bin.txt`（14,785,194 字节）。本次业务 UI 和热更代码有实际修改，需部署对应 Art／DefaultPackage 更新；相对上一构建仅 3 个 Art bundle、1 个热更 rawfile 及相应清单变化。

`Tools/output/home_mobile/deployment.json` 列出需发布文件、本地路径与目标 URL（排除构建报告和日志），资源文件先于总版本清单发布。该适配包含新的 AOT 组件，应搭配新底包。文件目前只在本地构建／暂存，未上传 CDN，微信开发者工具／真机需重新编译复测。


## 2026-10-22：小游戏网络与启动遮罩修复

- `WsClient` 原 WebGL 分支只有“不支持 ClientWebSocket”的占位。现在通过 `Assets/AOT/Scripts/Boot/WebSocketBridge.cs` 与 `Assets/Plugins/WebGL/GameWebSocket.jslib` 使用微信 `wx.connectSocket` / `SocketTask`；普通浏览器回退到 WebSocket。轮询收发在 Unity 主线程处理，包含连接超时、指数退避、手动重连和关闭清理。AOT 原生导入独立保留，避免热更 DLL 直接声明 P/Invoke。
- WebGL 的 `GameNet.Bind` 对本机或非 HTTPS/WSS 地址回退为 `https://game.xworld.ren` 和 `wss://game.xworld.ren/ws?pid={pid}&token={token}`，同时更新 BootContext，供业务 HTTP 使用。编辑器本机配置保留；自定义 HTTPS/WSS 远端地址保留。
- 截图中首次 `/login` 返回 401 后出现 `authed pid=...`，对应游客首次登录失败后自动注册成功，并非最终鉴权失败。ASTC 不支持后软件解压属于纹理兼容提示，与 WebSocket 占位错误不同。
- 原 Boot 固定两帧就隐藏遮罩，异步加载主界面时会暴露空白。现在等待热更通过 BootContext 通知主界面就绪；缺少 HUD 或超时保留可见错误提示，该信号不依赖登录或 WebSocket 成功。
- 验证：`node Tools/verify_game_websocket.js` 的 8 组实际 JS 桥接用例；`dotnet run --project Tools/Tests/WebSocket/WebSocket.csproj` 编译并执行实际 UNITY_WEBGL WsClient；Pipeline 的 `VerifyMiniGameNetwork.Endpoints` / `CheckUiReady` 与 `VerifyHomeMobileUi.CheckReady`。隔离场景验证完成后恢复原 Boot 场景。
- 新增 AOT / JS 桥接与上下文，必须搭配新底包和本次 DefaultPackage 热更，不能只刷新导出配置或只替换旧底包的热更 DLL。Art 未修改，无需重新构建或重复上传未变的 Art bundles。构建与发布清单见 `Tools/output/minigame_network/`；本地构建不自动上传 CDN。微信后台需配置 request 合法域名 `https://game.xworld.ren`、socket 合法域名 `wss://game.xworld.ren`。开发者工具和真机仍需运行复测。
本轮最终本地构建已成功（约 232 秒），底包目录 `AIClient/Build/WeChat/Base/minigame/`。首包数据 `06add2285b23eace.webgl.data.unityweb.bin.txt`（14,785,694 字节）；DefaultPackage 清单 `0e3722bbb19457d47bac35bbd4b516a7`，热更文件 `d34a46086ecefa40084479f551820a4e.rawfile`（253,440 字节）。Art 仍为 `006c201e92439eb03ae12d84b86f8fa6`，未变。已验证 4 个平台桥接原生导入、IL2CPP 返回字符串释放、生成 framework 中的桥接、Raw DLL 内容和清单 MD5；原 Boot 场景恢复，编辑器停止且编译完成。`Tools/output/minigame_network/deployment.json` 给出逐文件来源/URL，先发布资源文件，再发布总版本清单；未上传远端，未做微信真机联调。
后续线上核对：新首包 `06add2285b23eace.webgl.data.unityweb.bin.txt` 已返回 200；但 `/cdn/version.json` 仍下发旧热更版本 `5d00808a861cf2d9d5696eaafea5b896`，新 DefaultPackage 清单返回 404，导致新壳继续运行旧 DLL。已将本次缺少的 4 个 DefaultPackage 文件和 `cdn/version.json` 按网站路径整理到 `Tools/output/minigame_network/upload_patch/`，共 254,085 字节。将目录内容上传到网站 `/game/Friends/webgl/`，先 `yoo/DefaultPackage`，最后 `cdn/version.json`；首包与 Art 无需重复上传。仅本地整理，未执行上传。
## 2026-10-22：玩法 API 404 与预览紫色区域

线上新热更已生效，WebSocket 和主界面加载正常；`https://game.xworld.ren/game/state` 仍返回 404，且响应为 Kestrel。本仓库的完整玩法服务为 AIServer，Windows Server 上传/启动方式见 `AIServer/deploy/windows/README.md`。本地已生成并验证 `Tools/output/server_release/AIServer-Windows-x64.zip`，不含开发数据库，不自动替换旧服务；全部游戏域名路由需切到同一新后端，旧后端数据需要单独迁移。

实际 Art 材质仍保存旧抠底色 (0.07,0.02,0.09)，而热更代码改为紫色清屏，导致矩形显现；现已改为读取运行时材质 `_Key`。旧/新颜色的 GPU discard 与前景保留、隔离预览截图通过。客户端修复仅更新热更代码，无需底包/Art 重打：上传 `Tools/output/server_release/Client-CDN-Patch.zip` 解压内容到 `/game/Friends/webgl/`，先 `yoo/DefaultPackage`，最后 `cdn/version.json`。新 packVersion `587e28dfd1f166d117eadd24afa8efa1`，仍搭配既有支持 WebSocket 的新底包。两个 ZIP 均未上传线上。
## BuddyDefense 15888 部署地址（当前）

游戏服务已改为 `https://BuddyDefense.xworld.ren:15888` / `wss://BuddyDefense.xworld.ren:15888/ws?pid={pid}&token={token}`，CDN 资源路径维持既有部署。本轮 packVersion `d36750d301123c62fd6f673f324137a5`，发布文件 `Tools/output/server_release/Client-BuddyDefense-15888.zip`，仍先发布 yoo/DefaultPackage、最后发布 cdn/version.json。新常量会在编译时内联进热更 DLL，不增加运行时 AOT API 依赖；既有支持 WebSocket 的底包可直接更新热更，无需重打。

服务器包 `AIServer-BuddyDefense-15888.zip` 默认监听 `127.0.0.1:15888`。用户现有 Caddy 站点也监听 15888，需要加 `bind` 绑定服务器实际非环回网卡 IPv4，避免通配监听占用环回端口；`New-CaddySite.ps1` 在服务器运行可生成准确片段，保留 transport http 的 read_timeout/write_timeout 0。云服务器存在公网 NAT 时使用网卡私网地址绑定，域名 DNS 指向公网地址。更新已运行任务时先使用 Stop-Server.ps1，再安装新开机任务；更改 Caddy 后验证并 reload。需配置新域名的 DNS、证书及公网 TCP 15888 放行。当前本地验证正常，未部署远端。
客户端 ZIP 的网站发布辅助：将 `Publish-BuddyDefenseClient.ps1` 与 `Client-BuddyDefense-15888.zip` 放在同一目录，管理员 PowerShell 执行 `powershell.exe -ExecutionPolicy Bypass -File .\Publish-BuddyDefenseClient.ps1 -WebglRoot "网站中/game/Friends/webgl/对应的实际目录"`。也可先加 `-WhatIf` 检查。脚本校验清单 MD5，最后发布总版本；该目录属于静态资源站点，不是 AIServer 程序目录。发布后通过公网 `https://www.xworld.ren/game/Friends/webgl/cdn/version.json` 确认 packVersion 为 `d36750d301123c62fd6f673f324137a5`。新游戏域名的 DNS/TLS/15888 入口须先可访问。
### 2026-10-23 任务面板打开异常
TMP 会在多段文字下生成同名的 TMP_SubMeshUI 字体渲染子节点；PrototypeFlow.Panel 原先索引全部 Transform 时抛出重复键异常。现按组件排除内部渲染节点，保留业务节点绑定与重名校验。19 个业务面板（含任务、签到、背包、好友）预览场景验证通过。
本次仅发布 DefaultPackage 热更：packVersion `613942741fd3be253c86145d7451031c`，Art 保持 `006c201e92439eb03ae12d84b86f8fa6`。将最新 `Tools/output/server_release/Client-BuddyDefense-15888.zip` 放到服务器发布脚本旁，继续使用 `Publish-BuddyDefenseClient.ps1 -WebglRoot "C:\XWorld\CDN\Friends\webgl"`，脚本先写资源后更新 cdn/version.json。无需重打底包。未由 Agent 上传线上，发布后重新进入小游戏验证点击任务。