Godot 资源缓存与内存预算：什么时候保留，什么时候释放

背景：资源缓存与内存预算不是一个孤立功能

资源加载慢，所以我们想缓存；内存爆了，所以我们想释放。项目做到中后期，这两个目标会不断冲突。大厅、战斗、活动、角色预览、拍照模式都想保留自己的资源，低端机运行半小时后内存慢慢上涨，最后在切场景时崩溃。Godot 的 Resource 引用管理很方便，但也容易让资源被隐性引用留住。我们曾经关闭页面后纹理仍然没释放，查了很久才发现一个全局字典还缓存着 ViewportTexture。资源缓存需要预算、分级和可观察性。

缓存策略不是“用过就留”或“离开就删”。资源有不同热度、大小、重建成本和风险。主角常用资源值得保留，活动大图离开后应释放，Loading 常驻资源不能删，低内存时要有应急清理。若没有统一 ResourceCache，业务会各自保存引用，内存行为不可预测。

flowchart TD
    A["业务请求资源"] --> B["ResourceCache"]
    B --> C{缓存命中?}
    C -- "是" --> D["返回引用并更新热度"]
    C -- "否" --> E["加载资源并登记大小/类型"]
    E --> D
    B --> F["内存预算监控"]
    F --> G{超过预算或低内存}
    G -- "是" --> H["按优先级淘汰冷资源"]
    H --> I["释放引用/通知 owner"]
    G -- "否" --> B

缓存入口统一

业务不要自己维护各种 preload 字典。ResourceCache 提供 load_cached(path, policy)，policy 声明资源类型、优先级、是否常驻、owner、预估大小。统一入口才能统计命中率、内存和引用来源。少量真正常驻资源可以在启动清单里登记，其他资源都要有 owner 或淘汰策略。

落地时不要只把这一点写成口头规范，最好把它变成代码入口、配置字段或调试面板。负责实现的人需要说明它依赖哪些 Godot 节点、资源或平台能力，失败时如何降级，日志里能看到哪些字段，QA 应该怎样构造复现样本。资源缓存与内存预算相关问题通常不会在第一版立刻暴露，而是在内容量增加、设备差异扩大、运营活动叠加后变成偶现缺陷。提前把这些检查点固化下来，后续迭代会轻很多。

资源分级

我们把资源分成 pinned、hot、warm、cold。pinned 是 Loading、基础字体、默认材质；hot 是当前场景核心资源；warm 是刚离开但可能很快回来；cold 是可随时释放。场景切换时，当前场景资源从 hot 变 warm，过一段时间或预算紧张时变 cold。分级比简单 LRU 更符合游戏场景，因为有些资源虽刚用过但体积巨大，不适合保留。

落地时不要只把这一点写成口头规范，最好把它变成代码入口、配置字段或调试面板。负责实现的人需要说明它依赖哪些 Godot 节点、资源或平台能力，失败时如何降级，日志里能看到哪些字段，QA 应该怎样构造复现样本。资源缓存与内存预算相关问题通常不会在第一版立刻暴露，而是在内容量增加、设备差异扩大、运营活动叠加后变成偶现缺陷。提前把这些检查点固化下来，后续迭代会轻很多。

估算大小和真实观测

Godot 不总是直接告诉你完整显存占用，但可以估算纹理尺寸、音频长度、网格数据，再结合平台内存指标。估算不必绝对精确，关键是相对排序。开发面板列出最大资源、缓存总量、owner、最后使用时间和是否可淘汰。看到一个活动背景在离开活动后仍然 pinned，就能及时修。

落地时不要只把这一点写成口头规范，最好把它变成代码入口、配置字段或调试面板。负责实现的人需要说明它依赖哪些 Godot 节点、资源或平台能力，失败时如何降级，日志里能看到哪些字段，QA 应该怎样构造复现样本。资源缓存与内存预算相关问题通常不会在第一版立刻暴露，而是在内容量增加、设备差异扩大、运营活动叠加后变成偶现缺陷。提前把这些检查点固化下来，后续迭代会轻很多。

隐性引用排查

资源释放不了，通常是还有引用。UI 控件 texture、材质参数、全局数组、Tween 回调、信号闭包都可能持有资源。ResourceCache 可以在 debug 下记录借用栈或 owner，释放时若引用计数异常，输出可能来源。Godot 的引用模型很方便，但团队需要工具看见谁还拿着资源。

落地时不要只把这一点写成口头规范，最好把它变成代码入口、配置字段或调试面板。负责实现的人需要说明它依赖哪些 Godot 节点、资源或平台能力，失败时如何降级，日志里能看到哪些字段，QA 应该怎样构造复现样本。资源缓存与内存预算相关问题通常不会在第一版立刻暴露，而是在内容量增加、设备差异扩大、运营活动叠加后变成偶现缺陷。提前把这些检查点固化下来，后续迭代会轻很多。

低内存应急

移动端收到低内存警告时，立刻释放 cold 和 warm 资源，暂停非关键预加载，降低截图或 SubViewport 缓存。若仍然紧张，回到安全页面或提示重启。不要等系统杀进程。应急清理要避免释放当前场景必需资源，所以分级和 owner 必须准确。

落地时不要只把这一点写成口头规范，最好把它变成代码入口、配置字段或调试面板。负责实现的人需要说明它依赖哪些 Godot 节点、资源或平台能力，失败时如何降级，日志里能看到哪些字段，QA 应该怎样构造复现样本。资源缓存与内存预算相关问题通常不会在第一版立刻暴露，而是在内容量增加、设备差异扩大、运营活动叠加后变成偶现缺陷。提前把这些检查点固化下来，后续迭代会轻很多。

预加载和淘汰配合

预加载能减少等待，但会提前占内存。LoadingCoordinator 可以向 ResourceCache 申请预加载，带上过期时间和 owner。如果玩家取消进入目标场景，预加载资源降为 warm 或直接释放。不要让失败的加载任务留下大量缓存。预加载收益要用命中率衡量，命中率低的预加载就是浪费。

落地时不要只把这一点写成口头规范，最好把它变成代码入口、配置字段或调试面板。负责实现的人需要说明它依赖哪些 Godot 节点、资源或平台能力，失败时如何降级，日志里能看到哪些字段，QA 应该怎样构造复现样本。资源缓存与内存预算相关问题通常不会在第一版立刻暴露，而是在内容量增加、设备差异扩大、运营活动叠加后变成偶现缺陷。提前把这些检查点固化下来，后续迭代会轻很多。

缓存策略可配置

不同平台预算不同。桌面可以保留更多 warm 资源，移动端更激进，Web 端受内存限制更明显。ResourceCache 读取平台预算配置，按纹理、音频、场景资源分别设置上限。玩家切画质也可能影响缓存：高画质纹理更大，缓存上限要调整。

落地时不要只把这一点写成口头规范，最好把它变成代码入口、配置字段或调试面板。负责实现的人需要说明它依赖哪些 Godot 节点、资源或平台能力，失败时如何降级，日志里能看到哪些字段，QA 应该怎样构造复现样本。资源缓存与内存预算相关问题通常不会在第一版立刻暴露，而是在内容量增加、设备差异扩大、运营活动叠加后变成偶现缺陷。提前把这些检查点固化下来，后续迭代会轻很多。

验收和指标

长时间游玩测试非常重要：大厅和战斗来回切、打开多个活动、角色预览、拍照、资源包更新。记录内存曲线是否回落，缓存是否按预期淘汰，低内存是否触发清理。资源缓存系统的目标不是永远最省内存，而是在加载速度和稳定性之间做可解释的选择。

落地时不要只把这一点写成口头规范，最好把它变成代码入口、配置字段或调试面板。负责实现的人需要说明它依赖哪些 Godot 节点、资源或平台能力，失败时如何降级，日志里能看到哪些字段，QA 应该怎样构造复现样本。资源缓存与内存预算相关问题通常不会在第一版立刻暴露，而是在内容量增加、设备差异扩大、运营活动叠加后变成偶现缺陷。提前把这些检查点固化下来，后续迭代会轻很多。

场景退出要有资源审计

每个复杂页面或玩法退出时，可以在开发态做一次资源审计：本场景 owner 登记的资源是否全部释放或降级，是否仍有 pinned 之外的大资源被引用。审计不一定阻止运行，但输出清晰警告。比如“ActivityPage 退出后仍持有 3 张 2048 纹理”，路径和 owner 都列出来。这样内存泄漏在开发期就能被看到。

审计要避免误报。全局字体、Loading 图、主角常驻资源可以列入允许表。重点是页面私有资源、SubViewport 纹理、临时截图和活动大图。只要警告足够准确，团队会愿意处理。

缓存命中率决定是否值得缓存

不是所有资源都值得缓存。某个活动入口大图一天只打开一次，保留在内存里意义不大；背包常用图标和角色基础材质命中率高，值得保留。ResourceCache 统计资源命中率、平均加载耗时和占用估算。低命中、高占用资源应更快淘汰；高命中、低占用资源可以长期 warm。用数据调缓存，比凭感觉说“这个可能还会用”可靠。

预加载也一样。某个预加载资源如果 80% 情况没被使用，就应该调整触发时机或取消预加载。缓存系统要服务体验，不是把内存当仓库。

资源版本更新后的缓存失效

热更新或资源包切换后，旧资源缓存必须失效。ResourceCache 的 key 不应只有路径，还要包含资源版本或包版本。否则同一路径的新贴图上线后，客户端仍然拿旧引用。版本切换时，相关 owner 资源降级为 stale，当前场景可在安全时机替换，未使用资源直接释放。这个机制对活动皮肤和热修资源很重要。

接口约定

ResourceCache 的 policy 应该显式：priority、owner、estimated_size、evictable、version、ttl。没有 policy 的资源请求在开发态给 warning。这样团队会被迫思考资源生命周期。Cache 返回的句柄可以记录借用者，owner 销毁时自动 release。虽然 Godot Resource 本身有引用计数，但业务层仍需要语义化 owner。

自动化可以做进入退出页面十次的压力测试，记录缓存数量和估算内存是否回到基线。再模拟资源版本变化，确认旧版本 key 失效。内存问题通常晚暴露，自动化压力测试能提前发现增长趋势。

上线前的复盘方式

这类系统上线前，我会要求团队做一次小型复盘，而不是只看功能是否完成。复盘内容包括：这个能力的唯一入口在哪里，哪些页面或玩法已经接入，哪些路径仍然是旧实现；失败时玩家看到什么，日志能不能说明原因；低端设备、弱网、切后台、快速重复操作会不会改变结果；如果运营或美术改了资源，客户端有没有校验和降级。把这些问题逐条过一遍，通常能提前发现很多“不是 bug 但会上线出事”的边界。

复盘还要留下可执行资产。比如一个测试场景、一组假数据、一个调试开关、一份检查脚本。只写会议结论没有用，下一次迭代很快会忘。Godot 项目迭代速度快，越是快，越需要把经验沉淀成工具。否则每个版本都靠同一批人记忆项目细节，团队规模稍微扩大就会失控。

线上观测指标

上线后至少记录三类指标：使用次数、失败次数和耗时或资源占用。使用次数说明功能是否真的被走到；失败次数说明降级路径是否健康；耗时和资源占用说明它是否给性能带来压力。指标不需要一开始很复杂，但必须能按客户端版本、资源版本和设备档位拆分。很多 Godot 客户端问题只在特定设备或特定资源包上出现，没有这些维度，日志量再大也难定位。

当指标异常时，要能快速关闭或降级。功能入口、资源变体、表现强度、调试采样率都应有安全开关。工程系统成熟的标志，不是永远不出问题，而是出问题时能定位、能止血、能恢复。Godot 资源缓存与内存预算：什么时候保留，什么时候释放 这样的能力尤其如此，它连接了多个子系统，任何一个边界没守住，都可能表现成玩家端的偶现体验问题。

结语

Godot 客户端开发里，真正拉开项目质量差距的往往不是某个 API 的使用技巧，而是系统边界是否清楚。输入、动画、渲染、音频、UGC、富文本、网络、奖励和资源缓存都可以先做一个能跑的版本，但如果没有统一入口、状态机、调试面板和失败路径，后续内容量一上来就会变成难以维护的偶现问题。

我更倾向于把这些能力当作小型基础设施来做：先定义语义接口，再限定资源和数据边界，然后给开发和 QA 足够的观察工具。这样每次新增需求都不是往场景树里再塞一段临时代码，而是在已有规则里扩展一个新用例。项目长期运行时，这种朴素的工程秩序比一次性的聪明写法更可靠。