13 KiB
微信小游戏导出、导入与首包 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 保留规则见官方托管代码裁剪说明。
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）
启动不再自动加载 TownSquare/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 上传线上，发布后重新进入小游戏验证点击任务。