Unity TextMeshPro 中文缺字怎么排查:从字体表到回退链
中文游戏最让人头疼的字体问题之一,是编辑器里看起来正常,换一段文案或打包成多语言版本后却出现了方框、问号或空白字符。
这类问题通常不是“字体没导入”这么简单。TextMeshPro 最终能否显示一个字符,取决于当前字体资产、字体图集、本地回退链和 TMP 全局回退共同组成的字符覆盖范围。
先区分三种现象
1. 所有中文都不显示
优先检查:
- TMP Text 是否根本没有指定 Font Asset。
- 指定字体是否只包含拉丁字符。
- 字体资产是否导入了错误字体文件。
2. 大部分中文正常,少数生僻字缺失
这通常是当前字体图集没有对应字符,同时回退字体也没有覆盖它。常见于:
- 策划新增角色名或地名。
- 新语言包包含旧字体没有的字符。
- 品牌字体只覆盖常用字,没有配置系统字体或完整中文字体作为回退。
3. 本地编辑器正常,CI 或打包后异常
优先检查:
- TMP Essential Resources 是否在构建环境中导入。
- 字体资产和回退引用是否完整进入版本控制。
- 动态字体是否依赖了构建机没有安装的系统字体。
手工排查顺序
- 找到出现问题的
TextMeshProUGUI或TextMeshPro组件。 - 确认它使用的是哪个 Font Asset,而不是只检查 TMP Settings。
- 打开该 Font Asset,检查字符表或动态字体源文件是否包含目标字符。
- 如果主字体不包含,检查该 Font Asset 的本地 Fallback 列表。
- 再检查
Project Settings > TextMesh Pro > Settings > Fallback Font Assets。 - 修复后重新生成相关字体图集,并再次进入 Play Mode 或打包测试。
只看当前界面上有没有方框是不够的,因为未被场景加载的 Prefab 和 Localization 字符串表也可能藏着新字符。
哪些文本容易漏检
- 只存在于 Prefab,没有放进测试场景的按钮和提示。
- Unity Localization 的 StringTable 字符集。
- 仅在特定语言或活动期间出现的文案。
- 后续由服务器下发的文本。
- 运行时拼接、替换或从外部数据读取的文本。
前四类可以做静态扫描。运行时生成和远程下发的文本必须由项目自己的测试覆盖,静态工具无法证明它们一定安全。
用检查报告替代逐项点开
GlyphGuard 的检查流程是:
- 在编辑器中打开
Tools > GlyphGuard > Run Audit。 - 扫描 Prefab、场景中的静态 TMP 文本和 Unity Localization 字符串表。
- 检查字体本地回退链与 TMP 全局回退。
- 输出 HTML、JSON 和 JUnit XML 报告。
HTML 报告适合策划和 QA 查看,JSON 可用于自定义处理,JUnit XML 可以直接接入 CI 测试结果。
发布前建议的验收标准
- 所有 Error 级缺字问题已修复。
- 动态字体无法验证覆盖范围时,保留 Warning 并明确人工检查范围。
- 字体回退不存在空引用、重复项或循环。
- 构建环境使用和本地一致的字体资产。
- 至少用每个目标语言的新增文案跑一次完整扫描。
静态文本检查不能代替真机 UI 验收,但可以显著减少发布前最后一刻才发现缺字的情况。
相关工具:GlyphGuard - TextMeshPro 缺字与字体回退检查
检查范围仅包括工程中的静态文本和 Unity Localization 字符串表,不包括 OCR、远程下发或运行时动态生成的文字。