Go x/image/font/sfnt GlyphIndex 返回零为什么不一定是解析失败

GlyphIndex 返回的索引为零，同时 err 为 nil，表示该字体没有为查询字符提供对应字形，不能直接记成字体解析失败。先判断 error，再解释索引。字体能被解析、字符有对应字形、最终文字能正确排版，是不同层面的结论。

官方文档：https://pkg.go.dev/golang.org/x/image/font/sfnt

先分别判断错误和字形索引

sfnt.Parse 接收字体数据并返回 Font 与 error；GlyphIndex 则在 Font 上查询一个 rune 的字形索引。把这两个阶段的错误混在一起，会把普通字符覆盖不足误报成“文件损坏”。字体零号字形是缺失字符所用的特殊位置，通常称为 .notdef；它不等于 Go 的空指针。

查询结果只对应当前字体和当前 rune。某个字符缺字，不表示其他字符也无法使用；某个字符得到非零索引，也不能证明整个字体的所有数据都没有问题。

用完整函数保留三种查询状态

下面函数将缺字保存在 Missing 字段，把实际查询错误作为 error 返回。输入限定为单个字体的数据，不承担字体集合选取。ByteOffset 是 Go 字符串的字节位置，不是用户看到的第几个字符。示例没有绑定具体字体，也没有虚构运行结果。

package fontcheck

import (
    "fmt"
    "unicode/utf8"

    "golang.org/x/image/font/sfnt"
)

type Mapping struct {
    Rune rune
    ByteOffset int
    Index sfnt.GlyphIndex
    Missing bool
}

// Inspect 查询单字体的字符映射；不进行排版或渲染。
func Inspect(fontData []byte, text string) ([]Mapping, error) {
    if !utf8.ValidString(text) {
        return nil, fmt.Errorf("待查询文本不是有效 UTF-8")
    }
    f, err := sfnt.Parse(fontData)
    if err != nil {
        return nil, fmt.Errorf("解析字体: %w", err)
    }
    var b sfnt.Buffer // 工作缓冲区仅供当前串行查询使用。
    result := make([]Mapping, 0, utf8.RuneCountInString(text))
    for offset, r := range text {
        index, err := f.GlyphIndex(&b, r)
        if err != nil {
            // 查询失败时不能把尚未得到的映射伪装成普通缺字。
            return result, fmt.Errorf("查询 U+%04X，字节位置 %d: %w", r, offset, err)
        }
        result = append(result, Mapping{
            Rune: r, ByteOffset: offset, Index: index,
            Missing: index == 0, // 无错误的零索引按缺字语义记录。
        })
    }
    return result, nil
}

函数先明确要求有效 UTF-8，避免把无效字节经过字符串遍历后的替代字符误认为原始字符。真正存在的 U+FFFD 仍然作为普通 rune 查询。fontData 在 Font 使用期间保持不变；此处缓冲区仅在当前函数串行复用，不交给其他并发查询共享。

返回部分记录和错误时，调用方必须先处理错误，不能把已有记录自动当作整段检查完成。还应保留字体身份：不同 Font 的字形索引各有自己的含义，不能把一个字体查到的索引交给另一个字体加载。

比较缺字后的三种处理方案

缺字后的选择取决于应用目的。制作固定模板、必须完整覆盖的导出文件时，可以收集缺失 rune 并拒绝生成；允许有限展示时，可以接受缺字占位；需要多语言内容时，可以在应用内设计候选字体策略。下面比较的是处理方案，而不是引入无关字体工具。

GlyphIndex 自身不会搜索操作系统中的其他字体，也不会因为索引为零自动完成字体回退。若应用提供候选列表，应对每个候选分别处理查询错误和缺字结果；复杂文字还需要按实际排版单位制定回退规则，不能把逐 rune 换字体当成完整排版算法。

明确字符覆盖检查的适用范围

这个函数适合回答“这份字体对这些 Unicode 字符能否得到非零映射”。它不能证明连字、组合标记、双向文本或复杂文字塑形都正确，也没有检查最终像素表现。空格没有明显轮廓，并不意味着它必然缺字；应依据映射结果而非肉眼是否看见笔画判断。

GlyphIndex 接受 rune，不接受 UTF-8 编码中的单个字节。不要把 []byte(text) 的每个元素强转 rune 再查询，否则中文等多字节字符会被拆成错误的查询对象。字体集合也应先选定目标字体，再做同样的查询与记录。

常见疑问与选择表

是否应该用 ErrNotFound 判断缺字？对 GlyphIndex，应按其文档规定识别无错误的零索引。其他方法可能用 ErrNotFound 表示索引越界，不能把相邻 API 的约定套过来。

换一个字体得到相同索引，字形就相同吗？不能这样比较。索引属于具体字体，跨字体比较这个整数没有字符等价保证。

所有字符都有映射，就可以交付了吗？若任务只是字符覆盖检查，可以据此报告映射情况；若任务是排版或图片导出，还需要实际渲染链路处理相应能力。

选择时把“解析 error”“查询 error”“缺字记录”“排版结果”分别保留，既能避免误报，也能让应用准确决定拒绝、占位或使用候选字体。

参考：GlyphIndex 返回约定、Parse 文档。