在 Unity CI 中自动拦截 TMP 缺字:JUnit 报告与退出码门禁

字体缺字经常不是程序异常,没有崩溃日志,也不一定阻断构建。直到测试人员打开一个冷门页面,问题才暴露出来。

这类缺陷适合放进 CI:构建完成后、发布前扫描工程文本和字体回退,只要存在 Error 级问题就让流水线失败。

基本命令

GlyphGuard 可以在 Unity/Tuanjie 批处理模式中执行:

Unity \
  -batchmode \
  -nographics \
  -projectPath "$PWD" \
  -executeMethod GlyphGuard.Editor.GlyphGuardCI.Run \
  -glyphGuardOutput Artifacts/GlyphGuard \
  -quit

团结引擎可将 Unity 替换为对应的编辑器可执行文件。

工具默认在发现 Error 级缺字时以退出码 1 结束,否则返回 0。因此无需自己解析 HTML 才能决定流水线是否失败。

输出文件

默认会生成三类报告:

  • glyphguard-report.html:供策划和 QA 人工查看。
  • glyphguard-report.json:供自定义脚本、看板或归档。
  • glyphguard-report.xml:JUnit XML,可用于 GitHub Actions、Jenkins 等测试结果面板。

建议把 HTML 和 JSON 上传为构建产物,把 JUnit XML 交给测试结果步骤。

GitHub Actions 示例

- name: GlyphGuard
  run: |
    "$UNITY_PATH" \
      -batchmode \
      -nographics \
      -projectPath "$GITHUB_WORKSPACE" \
      -executeMethod GlyphGuard.Editor.GlyphGuardCI.Run \
      -glyphGuardOutput Artifacts/GlyphGuard \
      -quit

- name: Upload GlyphGuard reports
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: glyphguard-reports
    path: Artifacts/GlyphGuard/

if: always() 很重要。扫描失败时,你仍然需要 HTML 报告定位缺失字符。

推荐门禁策略

阻断发布

  • GG001:静态文本或字符串表存在缺字。
  • GG004:字体回退链出现循环。
  • 其他被项目团队定义为必须修复的 Error。

保留 Warning

  • GG002:TMP 文本没有显式指定字体。
  • GG005:回退槽为空或引用丢失。
  • GG008:动态字体没有可读取的源字体。
  • GG009:同一回退字体重复出现。

Warning 是否阻断发布取决于项目字体策略。关键是不要让“无法自动证明”被误当成“已经检查通过”。

不要直接扫描玩家构建包

GlyphGuard 是编辑器工具,应扫描源码工程中的 Prefab、场景、Localization 表和字体资产。先让工程导入和编译成功,再运行检查,最后构建 Player。

这样报告能保留组件路径和资源上下文,也更容易定位到具体文案。


相关工具:GlyphGuard - TextMeshPro 缺字与字体回退检查