Godot 运行时字体资源分包：多语言不是把所有字库塞进首包

为什么这个主题要放在资源和工具链之间

字体资源要按语言、场景和 fallback 分层，否则多语言上线会把首包和内存一起拉高。这类问题很少只属于运行时代码，也很少只属于发布脚本。它一头连着 Godot 的 Resource、场景、导入缓存和运行时加载，另一头连着团队协作、发布检查、QA 回归和事故复盘。只把它当成资源管理，工具链会缺口；只把它当成工具链，运行时又会缺少保护。

项目支持中文、日文、韩文、泰文和俄文后，字体文件突然变成首包大头。UI 团队为了保险把完整字库全部放进默认主题，启动时内存上涨，低端机首次打开邮件和公告还会卡。

所以本文把Godot 运行时字体资源分包当作资源和工具链交叉系统来设计。目标不是造一套很重的平台，而是让每一次资源变化都有来源、每一次工具判断有证据、每一次失败有恢复路径。

责任边界

建议先拆出这些模块：FontPackageManifest, LocaleFontResolver, GlyphWarmupQueue, FallbackChainValidator, FontDownloadGate, FontMemoryPanel。模块之间要通过结构化数据交互，不要互相读对方的临时字段。资源侧负责说明“我是什么、从哪里来、谁在用”；工具链负责说明“我检查了什么、为什么阻断、怎么修”；运行时负责说明“当前能不能继续、失败时怎么降级”。

核心字段可以先定为：locale, font_package_id, glyph_range, fallback_order, warmup_scene, loaded_bytes, missing_glyph_count, download_gate。字段看起来多，但它们能让 QA、程序、美术和发布同学站在同一张表上讨论问题。

架构图

flowchart TD
    N0["FontPackageManifest"] --> N1["LocaleFontResolver"]
    N1["LocaleFontResolver"] --> N2["GlyphWarmupQueue"]
    N2["GlyphWarmupQueue"] --> N3["FallbackChainValidator"]
    N3["FallbackChainValidator"] --> N4["FontDownloadGate"]
    N4["FontDownloadGate"] --> N5["FontMemoryPanel"]

图里的每个节点都应该能输出机器可读结果。Markdown 报告适合给人看，JSON 适合给 CI、趋势统计和发布平台消费。不要只输出一段彩色控制台日志，日志一滚过去，问题就失去上下文。

关键规则

• 首包只放默认语言核心字形
• 地区字体可选下载
• fallback 顺序必须可校验
• 缺字要降级显示并上报

这些规则最好写进提交检查或发布检查，而不是只放在文档里。文档能解释为什么，工具负责保证不会被忘记。需要临时豁免时，豁免也要有 owner、原因和过期时间。

实现骨架

下面的 GDScript 片段只表达一个习惯：检查结果要结构化，不能只有 true 或 false。

func build_check_result(id: StringName, owner: StringName, ok: bool, reason: String) -> Dictionary:
    return {"id": id, "owner": owner, "ok": ok, "reason": reason, "time": Time.get_ticks_msec()}

真实项目里还需要补 trace_id、resource_revision、build_id 和 owner。trace_id 串起一次检查，resource_revision 指向具体资源版本，build_id 指向产物，owner 让问题能被分配。

落地步骤

• 先做 dry run 报告，观察真实问题分布。
• 再把高风险规则接入发布检查，低风险规则保留 warning。
• 给每条失败项输出 owner、原因、建议修复方式和相关资源路径。
• 最后才做自动修复，避免工具在规则不稳定时批量改坏资源。

第一阶段只处理最容易出事故的资源类型或导出流程，不要一开始覆盖全项目。第二阶段把报告接到 PR 或发布检查，让失败能被看见。第三阶段再做趋势统计，观察哪些目录、哪些资源类型、哪些 owner 最容易出问题。

反例和边界

最常见的反例是“工具扫到了，但大家选择忽略”。如果忽略没有理由、没有期限、没有负责人，工具很快会变成噪音。另一个反例是运行时兜底过强，资源错误被占位图、默认字体、空特效悄悄掩盖，直到上线后才发现内容质量不对。

边界也要清楚。工具链不能替代美术判断美感，不能替代法务判断授权，也不能替代策划判断内容价值；但它可以保证信息完整、规则一致、风险可见。

QA 与验收样本

• 准备一个通过样本、一个失败样本、一个需要豁免的样本。
• 失败样本必须能稳定触发同一个错误码。
• 修复后报告要从失败变成通过，不能只靠人工确认。
• 样本要覆盖低端设备、渠道包和热更新资源。

QA 样本要固定到版本库或内部平台里，包含输入资源、预期报告、失败截图和修复方式。只靠口头说明，下一次换人就会丢失上下文。样本还能帮助工具升级：每次线上事故都应该转成一个新的样本，防止同类问题再次通过。

上线指标

建议观察阻断次数、误报率、修复耗时、豁免数量、同类问题复发次数和报告缺字段次数。指标不要只看总数，还要按资源类型、目录、平台、owner 和构建渠道拆开。

上线后还要看误报率和修复耗时。误报率高，团队会绕过工具；修复耗时长，说明报告没有给出足够定位信息。一个好的工具链系统不只是能发现问题，还能让问题被快速修好。

团队协作

这类系统涉及程序、美术、技术美术、QA、发行和运营。协作方式要写清楚：谁维护规则，谁批准豁免，谁处理报告，谁确认回滚。不要让工具报告变成没人认领的告警。

当团队开始把资源变化、导出变化和 QA 范围都当作可追踪对象时，批量内容生产会稳很多。资源不是文件夹里的静态文件，资源是会进入构建、运行、下载、回滚和客服排查的长期资产。

最小验收标准

我会用六条标准验收：检查结果可复现；报告能指出 owner 和原因；运行时有安全降级；发布前能阻断高风险问题；QA 有固定样本；历史趋势能回看。六条都满足，再考虑扩展到更多资源类型或更复杂的自动修复。

如果只能先做一件事，就先做 dry run 报告。让团队看到真实问题，再逐步把 warning 变成 blocking。直接一上来全阻断，往往会因为噪音太多被关闭；先让证据说话，工具才能站住。

额外细节

实际接入时，还要照顾旧项目。旧资源不可能一天内全部补齐字段，工具应该支持 unknown、legacy 和 approved 三种过渡状态。unknown 允许报告但不阻断，legacy 说明已知历史债务，approved 表示符合当前规则。

另一个细节是报告要能链接到具体修复位置。只说“资源不合规”没有帮助；要告诉维护者是哪一个文件、哪一条引用、哪一个导出预设、哪一个资源包闭包导致问题。报告越接近可操作，团队越愿意相信它。

主题专项验收

字体分包的验收样本要覆盖默认语言、切换语言、缺字 fallback、运营公告和离线启动。不要只在设置页切语言，还要在邮件、聊天、商店、成就和活动规则里看。字体下载失败时，客户端应该能用 fallback 显示可读文本，并告诉玩家当前语言包尚未完整，而不是让方块字直接出现在关键按钮上。

接入顺序建议

接入这类系统时，不建议一上来就全量阻断。第一步先做只读扫描，输出报告，让团队看到真实问题分布。第二步把最危险、最确定的规则变成发布阻断，例如正式包包含未授权资源、导出模板新增危险权限、资源预检必需依赖缺失。第三步再把 warning 分类，给每类问题设置 owner 和修复 SLA。这样工具不会因为一开始太吵而被关闭。

接入期间要保留人工豁免，但豁免必须结构化。至少包含 owner、原因、过期时间、影响范围和复查日期。没有过期时间的豁免，本质上就是绕过规则。每次发布前，工具应该列出仍然生效的豁免，让负责人重新确认，而不是把它们藏在配置文件角落里。

事故复盘模板

事故发生后，可以按同一个模板复盘：哪个资源或工具规则参与了链路，哪个字段缺失，哪个检查没有覆盖，运行时是否有降级，QA 样本是否能复现，发布报告是否提供了足够线索。这个模板能避免复盘只停留在“以后注意”。真正有价值的复盘会新增一个字段、一条规则、一个样本或一个阻断条件。

还要把复盘结果回写到工具里。比如一次因为字符串路径漏改导致资源缺失，就应该让 ReferenceRewriteEngine 学会扫描这种路径；一次因为许可证范围不清导致延期，就应该让 ProvenanceRegistry 增加 usage_scope；一次因为导出模板差异没人看懂，就应该让报告增加风险解释。工具链要从事故中长记性。

和运行时的关系

工具链检查不能替代运行时保护。即使发布前检查通过，客户端仍然可能遇到 CDN 抖动、磁盘不足、玩家离线、旧包残留或平台接口失败。运行时要有降级和提示，工具链要有预防和审计。两者的边界是：工具链尽量减少坏状态进入包，运行时保证坏状态出现时不伤害玩家资产和理解。

也不要让运行时保护掩盖工具失败。占位图、fallback 字体、默认材质都应该记录 reason_code，并在开发包或内测包里明显提示。正式包可以温和降级，但内部报告必须让团队知道发生了降级。否则 fallback 用得越好，资源质量问题越容易被拖到线上。

最后检查点

最终检查点不是工具能跑完，而是团队愿意依赖它。报告要短、准、可操作；错误要能定位到资源和 owner；修复后要能重新验证；历史趋势要能证明问题在减少。满足这些条件，工具才会成为生产流程的一部分，而不是某个程序员临时写的脚本。

实施清单

可以把实施拆成四张小卡。第一张卡只定义数据结构和报告格式，不做阻断；第二张卡接入一个真实目录或一个真实导出渠道，验证报告是否能被团队读懂；第三张卡加入 CI 或发布前检查，只阻断最确定的高风险项；第四张卡把修复样本固化成回归用例。这个顺序比一次性铺开更稳，因为工具链系统最怕刚上线就产生大量误报。

每张卡都要有验收标准。数据结构卡要能覆盖 owner、reason、resource_revision 和 build_id；报告卡要能定位到具体文件和建议修复方式；阻断卡要能解释为什么必须停；回归卡要能在修复前失败、修复后通过。没有验收标准，工具很容易变成“看起来跑了”的脚本。

报告字段示例

一条合格的报告至少应该包含：检查规则、资源路径、所属模块、风险等级、失败原因、建议修复、负责人、是否允许豁免、豁免到期时间、关联构建、关联资源版本。对于资源链路问题，还要包含引用来源和被引用目标；对于导出链路问题，还要包含旧值、新值和平台。字段越接近具体修复动作，沟通成本越低。

报告还应该区分 error、warning 和 info。error 阻断发布，warning 要进入修复队列，info 只做趋势观察。不要把所有问题都标红，也不要把所有问题都当提示。严重等级如果不准确，团队很快会对报告失去信任。工具链的第一原则不是严格，而是可信。

最后一条保护线

最后一条保护线是可回滚。任何自动检查、自动改写或自动阻断，都要能说明如何撤回。资源和工具链系统一旦进入发布流程，就不能只追求发现问题，还要保证修复路径清楚、回退成本可控、负责人明确。这样团队才敢长期依赖它。