Godot 导出包体审计：体积不是发布前一天才压的东西

包体体积是每天积累出来的

包体变大通常来自每天多一点的贴图、音频、测试场景和未清理资源。这个问题在项目早期经常被当成小功能，等内容量、平台数量和运营节奏上来之后才暴露成本。Godot 客户端要做的不是写一个临时脚本，而是把它当成可验证、可回滚、可观测的系统来设计。团队需要知道数据从哪里来，谁有权修改，失败后玩家看到什么。

先生成资源清单

资源清单要记录路径、类型、原始大小、导入后大小、引用场景和平台格式。先把输入和输出数据结构定下来，字段要有版本、来源、时间戳和校验结果。不要让每个页面或节点自己拼数据。统一模型能让编辑器工具、运行时逻辑和 QA 脚本读取同一份真相，也方便后续接入平台差异。

审计流程

导出审计应从 preset 生成 manifest，再做类型预算和依赖报告：

flowchart TD
    A["Export Preset"] --> B["Resource Manifest"]
    B --> C["Size Analyzer"]
    C --> D["Texture Budget"]
    C --> E["Audio Budget"]
    C --> F["Scene Dependency"]
    D --> G["Build Report"]
    E --> G
    F --> G
    G --> H["Review Gate"]

图里的每个节点都应该能单独记录耗时和失败原因。流程图不是文档装饰，而是帮助团队确认责任边界。某个阶段失败时，客户端应知道能否重试、能否降级、是否需要玩家确认。

贴图预算

贴图要按角色、UI、场景、法线等类别设置平台预算。把规则写成配置或 Resource，而不是散在 UI 和业务脚本里。比如阈值、白名单、黑名单、平台差异、灰度条件，都应该能在不改核心逻辑的情况下调整。配置也要有默认值和校验，缺字段时使用保守策略。

音频预算

长 BGM、语音和临时 WAV 是常见体积来源，多语言语音尤其要拆分。玩家看到的反馈要具体。只说失败没有意义，应该说明是资源不足、版本不兼容、网络不可用、数据已过期还是需要重新进入页面。Godot 的 UI 很容易弹一个 Toast，但真正关键的是 Toast 背后的错误码要稳定。

场景依赖和废弃资源

依赖链会把旧场景和废弃模型带进包，未引用资源也要列出。对性能敏感的部分要做预算。不要把所有检查都放到同一帧，也不要在战斗或切场景高峰做大扫描。可以用分帧任务、后台准备和安全点提交。低端设备上，稳定比一次性完成更重要。

平台差异

Android、iOS、桌面和 Web 的首包、安装包和加载策略不同。调试工具至少要显示当前状态、最近一次输入、最近一次输出、错误码、耗时和关联资源路径。很多线上问题不是算法错，而是资源、配置、平台状态不一致。把这些信息画出来，排查时间会大幅缩短。

报告要可读

报告要列出本次增长、最大资源、目录占比和引用来源。QA 场景要覆盖正常路径、异常路径、低帧率、断网、切后台、语言切换、平台差异和重复操作。只测一次成功是不够的。真正决定系统可靠性的，是失败后能否回到一个干净状态。

QA 和发布流程

发布前检查测试资源、调试配置、源文件和无用语言是否进入导出。上线后要有轻量指标，但不要上传无关隐私。记录聚合数量、失败阶段、资源版本、平台和耗时分布即可。通过这些数据，团队能知道问题是集中在某个平台、某个资源包，还是某个流程阶段。

落地建议

先做每日体积差异报告，让团队能看到新增体积来自哪里。落地时先做最小闭环：数据模型、执行流程、失败反馈、调试面板和一组 QA 用例。等闭环稳定，再扩展更多场景。Godot 给了足够的运行时自由度，工程上要补上的就是边界和纪律。

资源为什么会误进包

Godot 的导出并不总是只包含你以为的运行资源。测试场景在导出列表里，测试场景引用一套旧角色，旧角色又引用 4K 材质；一个 Theme 里挂着没用的大字体；一个示例视频放在 res:// 下没有排除。包体审计的第一价值，就是把这些隐形链路摊开。

报告里要能从大文件追到引用者。如果一个 80MB 音频被三个场景引用，删除前要知道哪个是真正入口。只列文件大小不够，引用路径才是行动线索。

贴图导入的默认陷阱

贴图导入默认值不一定适合所有平台。UI 图、法线图、遮罩图、HDR 环境图需要不同压缩。移动端如果把所有贴图都保留高质量，会直接放大包体和显存；Web 端又要考虑传输和解码。给目录设置导入规范很有用，比如 characters/hero 可以高一点，props/background 要严格限制。

还要检查贴图尺寸是否符合实际显示。一个在背包里只显示 96 像素的图标，不应该用 2048 原图进包。图标可以进图集，远景装饰可以降级。审计报告把贴图尺寸和引用 UI 尺寸对比，会发现很多浪费。

音频和视频

音频压缩要看用途。按钮音效短，可以保持低延迟；长音乐适合流式压缩；语音按语言拆分；环境循环要检查采样率。很多包体暴涨来自临时 WAV 或重复 BGM。视频更危险，一段宣传或教程视频可能几十到几百 MB，如果不是首包必需，应考虑下载或平台分发。

报告应按音频时长、格式、采样率、声道数分组。一个 3 秒音效 5MB，一眼就能看出异常。

构建差异门禁

不需要一开始就强制失败，但至少设置提醒阈值：单次包体增加超过 20MB，单文件超过 10MB，未引用资源超过一定数量，源文件类型进入导出。成熟后可以把部分规则变成门禁。门禁要允许白名单，例如新增章节确实需要大资源，但白名单必须写理由。

体积门禁不是为了阻止内容，而是让增长被看见。团队知道新增章节增加 300MB，可能接受；不知道为什么增加 300MB，就会在发布前恐慌。

和资源缓存的关系

首包体积和运行时下载是一起设计的。把资源移出包体不等于问题消失，只是转移到 CDN 和首次加载。审计报告可以区分 base package、optional package、runtime download。玩家第一次进入某个区域需要下载多少，也要有预算。否则首包小了，进入游戏后连续下载，体验同样差。

工程边界要写在代码之前

包体审计最怕“先能跑再说”。能跑的脚本往往把贴图、音频、场景依赖和导出 preset混在一个节点里，短期看起来省事，后期每个 bug 都要跨 UI、资源、网络和玩法一起查。开工前先写清楚边界：资源清单、导入设置、体积报告和发布门禁分别由谁负责，谁只读数据，谁可以提交状态变化，谁只能播放表现。边界清楚以后，新增需求通常只是加一个策略或 profile，而不是改一串互相调用的节点。

在 Godot 里，这个边界可以通过 Resource、autoload 服务和场景节点组合表达。Resource 保存可调规则，autoload 提供跨场景的状态和队列，场景节点负责当前画面表现。不要把全局状态藏在某个 UI 控件或临时子节点里。只要场景一切换，这类状态就会丢，问题还很难复现。

失败恢复要比成功路径先评审

成功路径通常很顺：玩家点击、系统执行、界面刷新。真正决定质量的是失败路径。测试场景进包、4K 图标、未压缩 WAV、多语言语音膨胀这些情况都不是边角料，而是实际测试和上线后最容易出现的问题。每个失败都要回答三个问题：当前状态是否还能继续，是否需要回滚，玩家需要知道什么。没有答案时，就不要把功能当作完成。

失败恢复还要避免二次伤害。比如恢复时又触发一次旧请求，清理时误删仍在使用的资源，回滚时把玩家新操作覆盖。可以给关键操作加 transaction id 或 version，恢复时只处理当前版本。旧回调、旧异步任务、旧动画事件到达时，如果版本不匹配就丢弃。这个小机制能挡住很多偶现问题。

性能预算不能等卡顿后再补

包体审计通常不是单次成本大，而是高频、叠加或峰值明显。预算要写成数字：每帧最多处理多少对象，每次扫描最多多少毫秒，本地队列最多多少条，缓存最多占多少空间，失败重试间隔如何退避。没有数字时，团队会凭感觉加功能，直到某个场景突然掉帧或磁盘暴涨。

预算也要有降级策略。低端设备、后台恢复、弱网、资源不完整时，系统应该知道哪些表现可以降低，哪些规则必须保持。表现层可以降，权威状态不能乱；调试信息可以少，关键错误不能吞；刷新频率可以降，玩家资产和输入边界不能省。预算不是单纯砍功能，而是把优先级提前讲清楚。

团队协作需要工具，而不是口头约定

包体审计经常跨程序、美术、策划、QA 和运营。只靠口头说“这个资源别这么配”“这个按钮别这样关”很快会失效。更可靠的是做小工具：编辑器检查、运行时调试面板、资源报告、状态导出、固定压测场景。工具不一定复杂，但必须让非程序也能看到问题所在。

例如检查器可以扫出缺字段、错误引用、超过预算的资源、不可回滚的状态；调试面板可以显示当前 profile、版本、队列、耗时、错误码；固定测试场景可以一键复现高峰。工具越早出现，团队越容易在内容制作阶段修问题，而不是等集成测试时集中爆炸。

上线验收清单

上线前至少检查这些项：正常路径是否稳定，失败路径是否可恢复，切场景和切后台是否安全，低帧率或弱网下是否有明确降级，日志是否能定位问题，玩家提示是否具体，配置缺失时是否保守，旧版本数据是否兼容，重复操作是否幂等，调试开关是否不会进入正式表现。这个清单看起来普通，但每一项都对应真实线上事故。

还要留一个回看机制。上线后一周看聚合指标和玩家反馈，确认失败率、耗时、回滚次数或异常状态是否在预期内。没有指标的功能，只能等玩家投诉。包体审计做得好，不是玩家会夸它，而是它在复杂场景里安静地工作，不把风险转嫁给玩家。

资源归档比直接删除安全

审计发现未引用资源后，不要马上删除。很多资源可能是下个版本内容、运营活动预置或编辑器工具使用。可以先移动到归档目录或在 manifest 中标记为 excluded，并记录负责人和过期时间。过期后仍无人认领，再删除。这样既能控制包体，又不会误删内容团队正在准备的资源。

归档目录必须被导出规则排除，否则只是换个地方继续进包。审计报告也要单独列出归档体积，避免仓库无限膨胀。包体优化和仓库治理不是一回事，但两者需要互相提醒。

推荐的最小实现顺序

第一步，写一个只统计文件大小和扩展名的脚本，输出按目录和类型聚合的报告。第二步，把报告和上一次导出结果对比，列出新增和增长最大的资源。第三步，加入导入设置检查，例如超大 PNG、未压缩 WAV、源文件进入导出目录。第四步，再做依赖追踪，找到大资源由哪些场景引用。

一开始报告不完美也没关系，只要每天稳定生成，团队就会开始关注体积变化。等大家习惯看报告，再加门禁和预算。包体优化的关键不是某个压缩技巧，而是让体积增长无法悄悄发生。

上线后的维护

包体审计上线后，最好把报告放进每次版本评审。新增章节、活动资源和平台专属资源都要说明体积变化。体积增长不是不能接受，但必须能解释。能解释的增长是内容成本，不能解释的增长才是风险。

团队交接说明

团队交接时要把体积预算拆到目录和资源类型。角色、场景、UI、音频、视频、字体分别有负责人和阈值。报告发现增长时，能直接找到沟通对象。没有责任边界时，包体问题会变成所有人的问题，也就等于没有人负责。预算不是限制创作，而是让创作知道成本。

额外注意点

最后要区分仓库体积和导出体积。仓库里可以保留源文件、PSD、Blender 文件和高质量母版，但它们必须明确不进入导出。导出体积报告只看玩家下载成本，仓库治理看团队协作成本。两个指标都重要，但不要混在同一张表里讨论。

历史追踪

包体审计还要保留历史趋势。单次版本看不出问题，连续十个版本的曲线能说明资源策略是否失控。趋势图里标注大版本、活动和平台扩展，评审时更容易判断增长是否合理。