cYz26 Godot Web 中文字体修复与优化
当 Godot 导出 Web（HTML5）后出现中文方块、空白、符号乱码，或需要降低字体导致的包体积时，使用此 skill。
1) 触发条件与根因判断（必须先做）
确认至少命中以下两项：
- 编辑器内中文正常，Web 导出后变方块/空白/乱码。
- 项目未明确使用随包 CJK 字体，或仍依赖系统字体回退。
- 替换字体后大部分中文正常，但个别符号（如
→、✕）显示异常（典型子集缺字）。
若命中，进入“随包字体 + 子集化”流程，不要先尝试用系统字体规避。
2) 基线修复策略（推荐做法）
- 使用可分发开源字体，放入
res://assets/fonts/。 - Web 运行时主动加载随包字体，避免浏览器/系统回退差异。
- 字体优先输出
woff2子集文件，减少首包下载体积。 - 字体源文件不内置在 skill 中，使用时按需下载并缓存（默认
~/.codex/cache/fonts）。
推荐基线字体：
Noto Sans CJK SC/Source Han Sans CN（OFL）- 不推荐仅依赖系统字体（Web 环境不可控）
3) 当前工程落地路径（Godot 4）
- 在
scripts/main.gd维护WEB_PACKAGED_FONT_PATH指向随包字体。 - 在
_configure_runtime_ui()中仅在OS.has_feature("web")时注入theme.default_font。 - 避免把修复建立在系统回退之上；系统回退只可作为兜底，不可作为主路径。
4) 字体子集化与包体优化（核心）
默认顺序：
- 先修“能显示”再修“更小”。
- 若本地无源字体，先执行
skills/godot-web-cjk-font-fix/scripts/fetch_font.sh下载并缓存。 - 子集化优先复用工程脚本：
make subset-font（tools/font_subset.sh）。 - 子集字符提取必须覆盖工程中全部可打印字符，避免漏掉
→这类符号。 - 字体产物使用
woff2，同时保留glyphs_project_full.txt便于回溯与复现。
额外体积优化（和字体并行）：
- 清理未运行时使用的素材目录（用
.gdignore阻断导出扫描）。 - 每轮优化后对比
build/web、index.pck、index.wasm，明确收益来自哪里。
子集化细节见：
references/font-subsetting.md
5) Web 验证（强制）
按顺序执行：
make subset-font（变更文案或字体后）make export-webmake web-smoke
手动回归：
cd build/webpython3 -m http.server 8000- 打开
http://127.0.0.1:8000/index.html
验收清单：
- 教程、设置、反馈弹层、主界面中文全部可读。
- 符号类文案（如
→、✕、中文标点）无方块/乱码。 - 导出产物中存在字体资源，浏览器网络面板无 404。
6) 故障排查顺序
若仍无法显示中文，按以下顺序排查：
- 字体路径是否正确（
res://...），并已生成.import。 - 是否有独立
Theme覆盖运行时注入字体。 - 子集字体是否缺字：优先检查
scenes/*.tscn、scripts/*.gd的符号字符。 - 文案更新后是否忘记重跑
make subset-font。 - 缓存字体下载是否失败（网络或 URL 不可达）；必要时设置
FONT_SOURCE_URL指向可访问直链。 - 是否受浏览器缓存影响（强刷或版本号变更后复测）。
7) 交付输出要求（必须）
每次处理后必须输出：
- 使用的字体文件与许可来源。
- 字体应用方式（运行时全局注入/局部覆盖）。
make subset-font、make export-web、make web-smoke结果。- 优化前后体积对比（至少
build/web、index.pck、index.wasm）。