Go x/image/font/sfnt GlyphIndex 怎样查询字符对应字形

如果 TTF 或 OTF 字体能正常解析，但某个字符显示成缺字方框，先不要急着怀疑渲染器。用 golang.org/x/image/font/sfnt 时，最直接的排查点是 Font.GlyphIndex：它把一个 Go rune 映射到字体内部的 GlyphIndex。当字体没有这个字符时，接口会返回 0, nil，这里的 0 表示特殊的缺字字形，而不是一次调用失败。

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

缺字症状先看 GlyphIndex 是否为 0

一次字体排查中，最容易误判的现象是“解析成功，所以字符一定存在”。sfnt.Parse 只说明输入数据符合可解析的 SFNT 字体结构，并不保证字体覆盖所有 Unicode 字符。字符显示异常时，可以把问题拆成两层：字体文件是否能解析，以及这个 rune 是否能映射到有效字形。

GlyphIndex 正好位于这两层之间。它查询的是字体的字符映射表，返回值为 0 时，官方文档规定这代表没有对应字形；很多字体把索引 0 的特殊字形称为 .notdef。因此，0 是一个有意义的结果，不能只用 err != nil 判断成功。

用 sfnt.Parse 和 GlyphIndex 建立最小查询

下面的示例使用 goregular.TTF 作为内置字体数据，重点不在渲染，而在展示查询链路。真实项目中也可以把字体文件读入字节切片，再交给 sfnt.Parse。

package main

import (
    "fmt"
    "log"

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

func glyphIndexFor(r rune) (sfnt.GlyphIndex, error) {
    // Parse 只建立字体解码对象，Font 使用期间底层字节仍要保持可用。
    f, err := sfnt.Parse(goregular.TTF)
    if err != nil {
        return 0, fmt.Errorf("解析字体失败: %w", err)
    }

    var buf sfnt.Buffer
    // 复用 buf 保存本次查询的临时工作区，避免每次调用都创建新 Buffer。
    index, err := f.GlyphIndex(&buf, r)
    if err != nil {
        return 0, fmt.Errorf("查询字形索引失败: %w", err)
    }
    return index, nil
}

func main() {
    index, err := glyphIndexFor('G')
    if err != nil {
        log.Fatal(err)
    }
    // 0 是“没有对应字形”的正常返回值，需要单独处理。
    if index == 0 {
        log.Println("字体没有覆盖这个字符")
        return
    }
    fmt.Println("GlyphIndex:", index)
}

这里有三个需要固定下来的判断：Parse 的错误属于字体输入问题；GlyphIndex 的非空错误属于查询过程问题；index == 0 则是“没有映射字形”的业务分支。把三者混在一个 if err != nil 中，往往会让缺字继续流入后续轮廓或尺寸查询。

为什么 GlyphIndex=0 不是 ErrNotFound

字符到字形的映射和“按索引读取字形信息”是两件事。GlyphIndex 接收的是字符，字符没有映射时按照 SFNT 的约定返回 0；而 GlyphName、GlyphBounds、GlyphAdvance 和 LoadGlyph 接收的是已经得到的字形索引。后几类方法在索引越过字体范围时，才会返回 sfnt.ErrNotFound。

所以排查链路应该先判断 0，再决定是否继续取名称、尺寸或轮廓。不要为了“让后续调用报错”而把 0 强行改成一个看似有效的索引，那会把明确的缺字变成更难解释的字形数据。

func describeGlyph(f *sfnt.Font, r rune) (string, error) {
    var buf sfnt.Buffer
    index, err := f.GlyphIndex(&buf, r)
    if err != nil {
        return "", fmt.Errorf("字符映射失败: %w", err)
    }
    if index == 0 {
        // 0 表示字体没有为该 rune 提供可用字形，调用方应选择缺字策略。
        return "missing glyph", nil
    }

    name, err := f.GlyphName(&buf, index)
    if err != nil && !errors.Is(err, sfnt.ErrNotFound) {
        return "", fmt.Errorf("读取字形名称失败: %w", err)
    }
    // 字体可能没有名称表；空名称不等于 GlyphIndex 查询失败。
    return fmt.Sprintf("index=%d name=%q", index, name), nil
}

Buffer 和字体数据的生命周期要一起看

sfnt.Buffer 是可选参数，传 nil 也能完成一次调用；在批量检查字符串时，显式复用一个 Buffer 通常更合适。需要注意的是，复用意味着“同一时刻由一个调用方使用”。官方文档允许不同的 Font 方法并发执行，但每次调用应使用不同的 Buffer，或者都传 nil。

另一个容易被忽视的边界是字体源数据。使用 sfnt.Parse 时，底层 []byte 在 Font 仍然使用期间不能被修改；使用 ParseReaderAt 时，底层 io.ReaderAt 也不能提前关闭。若把字体对象放进长期缓存，就要同时管理它引用的字节切片或文件。

拿到索引后再读取名称、边界和轮廓

索引查询只回答“字符对应哪个字形”，不负责把字形画成像素。若下一步是排版，可以读取 advance 和边界；若下一步是矢量处理，可以调用 LoadGlyph。这些方法共享同一个索引概念，但每个方法的失败边界不同。

func inspectGlyph(f *sfnt.Font, r rune) error {
    var buf sfnt.Buffer
    index, err := f.GlyphIndex(&buf, r)
    if err != nil {
        return err
    }
    if index == 0 {
        // 没有索引就不要继续请求名称、边界或轮廓。
        return fmt.Errorf("字符 %q 没有对应字形", r)
    }

    name, err := f.GlyphName(&buf, index)
    if err != nil && !errors.Is(err, sfnt.ErrNotFound) {
        return err
    }
    bounds, advance, err := f.GlyphBounds(&buf, index, fixed.I(32), font.HintingNone)
    if err != nil {
        return err
    }
    segments, err := f.LoadGlyph(&buf, index, fixed.I(32), nil)
    if err != nil {
        // 彩色字形可能不是可直接返回的单色矢量轮廓。
        if errors.Is(err, sfnt.ErrColoredGlyph) {
            return fmt.Errorf("字形 %q 是彩色字形，不能按单色轮廓处理", r)
        }
        return err
    }
    fmt.Printf("name=%q bounds=%v advance=%v segments=%d\\n", name, bounds, advance, len(segments))
    return nil
}

这段代码需要补齐 errors、golang.org/x/image/font 和 golang.org/x/image/math/fixed 的导入。它没有假设每个字体都有 glyph name，也没有把彩色字形当作普通单色轮廓；在生产代码中，应根据业务需要决定回退字体、跳过轮廓，还是交给更高层的排版包。

把排查结论固定成一条短链路

实际处理缺字时，可以把判断压缩为：先确认字体成功解析，再用 GlyphIndex 查询字符；返回 0 就走缺字策略，返回非 0 才继续取名称、度量或轮廓；后续方法报 ErrNotFound 时检查索引范围；并发批量查询时给每次调用独立的 Buffer。这样既不会把正常缺字误报成系统错误，也不会把 Buffer 或字体源数据的生命周期问题藏在渲染层。

常见问题

GlyphIndex 返回 0 时应该直接返回 error 吗？

不一定。0 是接口约定的缺字结果，是否升级成业务错误取决于场景：编辑器可以换回退字体，批处理可以记录并跳过，严格校验则可以把它包装成业务错误。

可以让多个 goroutine 共用一个 sfnt.Buffer 吗？

不建议。Buffer 是可复用的临时工作区，同一时刻应只服务一个调用；并发时为每个调用准备独立 Buffer，或者传入 nil。

GlyphName 为空是不是 GlyphIndex 查询失败？

不是。部分字体没有 glyph name，GlyphName 可能返回空字符串和 nil。只要 GlyphIndex 非 0，仍然可以继续读取边界、advance 或轮廓。

GlyphIndex 能直接把字形渲染成图片吗？

不能。sfnt 是低层解码 API，GlyphIndex 只给出索引；读取轮廓后还需要矢量栅格化或使用更高层的字体包完成绘制。