根本原因是freetype不自动加载字体，需手动读取文件、用truetype.parse解码为*truetype.font并检查错误；常见问题包括渲染方块、panic或nil指针，多因parse失败未校验或字体格式/完整性异常。
Go 用 freetype 渲染文字时字体文件不生效
根本原因是 freetype 本身不加载字体，它只解析已加载的 *truetype.Font；你得自己读取字体文件、解码成 truetype.Font 实例，再传给 freetype 的 DrawString 或光栅器。
常见错误现象：DrawString 渲染出方块、空格、或 panic 报 nil pointer —— 八成是 truetype.Parse 失败后返回了 nil，但没检查错误就直接用了。
- 务必用
ioutil.ReadFile（Go 1.16+ 改用os.ReadFile）读取字体文件二进制内容，不能传路径字符串 -
truetype.Parse只接受[]byte，返回*truetype.Font, error，错误必须检查，失败时不能跳过 - 某些 .ttf 文件含多个字体面（font face），
truetype.Parse默认只取第一个；如需指定，得用truetype.ParseWithIndex并传入 index（通常为 0）
truetype.Parse 返回 nil 但没报错？检查字体文件完整性
这不是 bug，是 golang.org/x/image/font/truetype 的设计：当字体内嵌表损坏、校验失败、或非 TrueType/OpenType 格式（比如 .woff/.otf 混用）时，Parse 可能静默返回 nil, nil —— 这是已知行为，不是异常。
使用场景：从网络下载字体、或用户上传字体时尤其容易中招。
立即学习“go语言免费学习笔记（深入）”；
- 先用系统命令验证：
fc-list : file | grep your-font.ttf（Linux）或双击 macOS 预览字体文件看能否正常打开 - 在 Go 中加一层保护：读取后检查前 4 字节是否为
[\x00\x01\x00\x00]（TrueType）或[O,T,T,O]（OpenType），避免传入乱码 - 别依赖
errors.Is(err, nil)判断成功；正确写法是if font == nil { log.Fatal("invalid font data") }
freetype.Context.SetFontFace 不生效的典型配置漏项
freetype.Context 是状态机式对象，SetFontFace 只设置当前字体，但真正影响渲染的是后续调用 DrawString 时的 fixed.Point26_6 坐标和 draw.Drawer 的 Dst/Src 配置。
性能影响：每次 SetFontFace 不会重解析字体，只是绑定缓存的 *truetype.Font 和字号（fixed.Int26_6），开销极小；但频繁切换不同字体实例会增加 cache miss。
- 必须在
DrawString前调用SetFontFace，且传入的是&text.Font{Font: font, Size: 12 * 64}（注意单位是 1/64 像素） -
Size必须转成fixed.Int26_6，别直接写12；正确写法：fixed.Int26_6(12 * 64)或fixed.I(12).Mul(fixed.I(64)) - 如果渲染模糊，大概率是
Size设太小（导致采样不足）或Dst图像分辨率与逻辑尺寸不匹配
中文等多字节字符显示为方块？编码和 glyph 映射才是关键
freetype + truetype 库本身不处理 Unicode 到 glyph ID 的映射，它只按你给的 rune（int32）查字体里的 cmap 表。如果字体不含对应 Unicode 区段（比如很多英文 TTF 不带 CJK Unified Ideographs），就会 fallback 到 .notdef glyph —— 就是你看到的方块。
兼容性影响：不是所有中文字体都完整覆盖 GB2312/UTF-8 常用字；有些“免费中文字体”实际只含 ASCII + 基本标点。
- 用
font.GlyphIndex手动查某个 rune 是否有对应 glyph：if gid := font.GlyphIndex(r); gid == 0 { /* missing */ } - 优先选 Noto Sans CJK、思源黑体这类明确标注“支持 UTF-8 全区”的字体文件
- 避免用
string([]byte{...})构造文本；确保输入是合法 UTF-8string，且遍历用for _, r := range text而非for i := range text
最常被忽略的点：字体文件路径权限、跨平台换行符导致的读取截断、以及把 truetype.Font 实例当成全局变量复用时，没意识到它的 Metrics 是只读但不可并发安全——如果多 goroutine 同时调用 GlyphIndex，没问题；但若你手动改了内部字段，就踩坑了。
