在 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。
这样报告能保留组件路径和资源上下文,也更容易定位到具体文案。