从 Cocos 工程构建微信产物
适用:Cocos Creator 3.8.8 + TypeScript;官方说明按 3.8 LTS 维护。资料核查:2026-11-17。本节描述可执行工作流,未声称本课程已构建微信包或通过真机验证。
构建解决的是目标转换
编辑器工程由场景、预制体、资源、脚本与元数据组成,微信开发者工具读取的是平台项目产物。把工程目录直接导入开发者工具,不会替你完成 Cocos 资源导入与引擎适配。浏览器预览也不是微信包:它们共享大量业务代码,却使用不同启动入口、平台接口与资源配置。先明确产物从哪里生成、被谁读取,排错才不会围着错误目录反复刷新。
保留四种身份:源码提交或快照标识、Cocos 编辑器版本、构建配置标识、产物版本。开发者工具里的项目名称只是标签,不能唯一识别某一次构建。每次收集证据时把这四种身份写入记录,最好在调试信息页显示客户端版本与规则版本。否则同事报告的问题可能来自昨天的包,而你检查的是今天的源码。
第一次构建先减小变量
先选择一个只包含入口 UI 与基本输入的场景,确认它在浏览器正常,再在构建面板新建微信小游戏目标。设置真实项目的 AppID、初始场景、参与构建的场景和输出位置,保留配置用于后续重复构建。AppID 标识平台项目,不是 AppSecret;公开标识可出现在产物,服务端秘密不能进入构建配置。
完成构建后,打开输出目录确认入口与平台配置确实存在,再由开发者工具导入该目录。不要凭“编辑器构建完成”就判断工具读取到了新产物;工具可能仍打开另一目录。检查其项目根路径和运行时展示的版本标识。临时修复产物文件只用于验证假设,正式修复要落回构建输入或受控构建扩展,否则重建就会消失。
| 层 | 输入 | 主要产物或证据 |
|---|---|---|
| 源码检查 | TS、配置、规则 | 类型检查与规则测试结果 |
| Cocos 构建 | 工程与目标配置 | 微信平台项目目录、构建日志 |
| 开发者工具 | 平台项目目录 | 编译结果、模拟器日志、预览入口 |
| 微信真机 | 预览或体验版本 | 机型、基础库、画面与运行日志 |
场景引用决定哪些资源进入包
“删除不用的场景”不一定删除所有多余资源。场景、预制体、resources 目录与 Bundle 的收集规则不同,静态引用又会把依赖带入包。启动场景若直接引用整套关卡预制体,就算代码准备按需加载,也可能已经把大量资源拉进首包或启动依赖。用构建结果和依赖报告确认资源归属,不能只看目录名字。
先画出入口到首个可玩场景的依赖图:启动 UI、字体、首关场景、角色纹理、音频与规则表。非首局必需资源移出启动依赖,由后续流程加载。Bundle 是模块化资源组织方式,微信分包是平台分发机制,二者有联系但不等同。具体拆分与缓存见分包与加载。
调试与发布配置要成对验证
调试构建方便看日志和源码,发布构建可能压缩脚本、合并资源并改变初始化时机。某些问题只在发布模式暴露,例如依赖函数名、错误使用内部属性、动态加载路径或反射假设。正式发布前至少用一次与发布相同配置的候选包完成核心闭环,不能只交调试包测试报告。
Source Map 用于把压缩栈映射回源码,应与对应产物一起保存,版本必须一致。它可能包含源码与内部路径,公开策略由项目决定;不能把密钥放在源码后寄望关闭 Map 保护秘密。调试日志要有等级和采样,不能逐帧打印大量对象再拿测得帧率当发布性能。
纹理格式、渲染后端、引擎裁剪和性能模式都属于影响行为的构建变量。每次只调整可解释的一组变量,保存前后报告。高性能模式等平台能力可能有开通和兼容要求,不能因为构建面板有开关就视作账号已具备。这里不写未经当前平台核实的开通路径或设备内存限额。
构建失败按阶段定位
脚本编译失败先看第一条业务错误,后续大量错误可能只是级联;资源导入失败查源文件、元数据与 UUID 引用;构建成功但启动黑屏查最早启动日志、入口场景、平台适配和资源请求。不要先删除整个工程缓存作为通用疗法,它可能暂时隐藏问题而丢失可复现条件。
若干净工程能构建、当前工程不能,可以逐个加入场景与插件定位最小差异。若仅某台机器失败,比较编辑器补丁版本、依赖锁文件、导入结果和输出路径。多人协作要保留资源元数据,避免同一资源在不同机器生成不同身份。生成目录可以重建,手工绘制的资源和元数据不能被当作缓存清理。
自动化从可复现配置开始
先在本地用受控配置完成命令行构建,再接 CI。命令行应使用已安装且固定的编辑器路径,参数从 3.8 文档与实际构建配置核对;不要随意拼一个旧版本命令。CI 保存构建日志、清单、体积统计与产物哈希,而不只是显示绿色状态。上传、提交审核与发布是后续状态,不能由构建成功推断。
一个小型构建记录可包含 editor、platform、sourceRevision、configDigest、artifactDigest、scenes 和 ruleVersion。字段值来自实际过程;没有构建过的字段标为未执行,不能让 AI 自动填“通过”。任何手动更改产物的操作都要重新计算身份,防止测试材料与最终包不一致。
资源元数据是源码的一部分
Cocos 用资源身份维护场景和预制体引用,团队移动或重命名资源时应通过能保留其身份的受控流程进行。丢失元数据后即使文件内容没变,引用关系也可能变化。审查资源改动不能只看图片预览,还要看新增、删除和身份变化是否符合意图;大量无关元数据重写可能说明导入环境或版本发生漂移。
构建检查可以对比关键资源清单,发现入口场景、首关预制体或必要字体是否被遗漏。这个检查不证明资源能正确渲染,却能在打开开发者工具之前发现明显打包错误。把静态存在检查与运行验证分开,失败信息更准确,自动化也更容易维护。
交给 AI 的任务与验收
可复制任务:“整理 Cocos 3.8.8 的微信构建配置与产物检查脚本。保留入口场景、目标平台、AppID 占位与版本清单;列出 resources、Bundle 和静态引用带入的资源。生成分阶段检查说明,不调用上传、不写入密钥,不把浏览器测试写成微信测试。”
验收从新输出目录能识别唯一产物;入口场景正确;发布候选配置与报告一致;构建失败能指出阶段和第一条有效错误。之后按工具与真机流程验证平台行为,而不是继续停留在编辑器里推断。
官方来源
- Cocos 3.8 微信发布:目标平台构建入口。
- Cocos 3.8 构建选项:场景与资源收集、调试和 Source Map。
- Cocos 3.8 命令行发布:自动构建依据;示例参数须结合实际安装核对。