Go gofpdf 字体注册成功为何仍可能缺字

我第一次遇到这个问题时，日志里没有明显报错：AddUTF8Font 已经调用，PDF 也能生成，但中文标题或少数字符仍然显示为空白。后来把问题拆成“字体资源有没有加载”“输出时用的是哪一个字体”“这个字体有没有目标字形”三层，定位就快很多了。

gofpdf 官方文档把 AddUTF8Font 定义为导入带 UTF-8 符号的 TrueType 字体；它要求先准备字体定义文件，JSON 定义文件以及嵌入字体文件必须位于 New() 或 SetFontLocation() 指定的目录。官方资料入口是 https://pkg.go.dev/github.com/jung-kurt/gofpdf。因此，“注册成功”只证明导入链路基本成立，不等于字体覆盖了正文里的每一个字符。

最稳妥的判断方式，是沿着“定义文件与字体文件 → SetFont 家族/样式 → 字符是否有字形 → 子集是否包含字符”逐层检查。不要只看 AddUTF8Font 是否被调用。

注册成功和显示完整是两件事

gofpdf 的字体使用至少有两个名字：注册时传给 AddUTF8Font 的家族名，以及输出前传给 SetFont 的家族名。前者负责把资源放进字体表，后者决定当前文字实际使用哪套资源。如果两处名称不同，或者样式参数没有对应的定义文件，PDF 可能仍能生成，但文本会落到错误字体、空白字形或不完整的样式资源上。

另外，UTF-8 只描述字符编码方式，不会给字体凭空增加字形。一个主要覆盖拉丁字符的字体可以正常显示英文和数字，却没有中文、扩展汉字或某些符号；这时注册过程没有问题，缺字发生在字形覆盖层。

先把字体资源链路对齐

官方文档说明，AddUTF8Font 需要先使用 makefont 工具生成字体定义文件，并从字体目录加载 JSON；嵌入字体时还要让对应字体文件可被找到。下面这个最小示例把目录、家族名和样式名写在一起，便于排查。

package main

import "github.com/jung-kurt/gofpdf"

func main() {
	// fontDir 中要同时放置 dejavu.json 以及嵌入所需的字体资源。
	pdf := gofpdf.New("P", "mm", "A4", "./fonts")
	pdf.AddPage()

	// 家族名是应用层别名，后面的 SetFont 必须使用同一个名字。
	pdf.AddUTF8Font("report", "", "dejavu.json")
	pdf.SetFont("report", "", 14)
	pdf.Cell(0, 10, "中文标题与 English title")

	// 输出前先读取 gofpdf 自己记录的错误，避免把加载失败误认为缺字。
	if !pdf.Ok() {
		panic(pdf.Error())
	}
	_ = pdf.OutputFileAndClose("report.pdf")
}

这里的关键不是路径写成了哪种形式，而是三件事保持一致：字体目录确实是当前实例的读取目录，dejavu.json 的基础名与注册参数一致，SetFont 的家族和样式确实指向已经注册的资源。若 JSON 找不到，官方文档描述的错误是“Could not include font definition file”；这属于加载问题，不要直接归因于缺字。

确认输出时没有切换到另一套字体

我更容易忽略的是样式。注册了普通体并不自动提供粗体和斜体资源。gofpdf 的文档示例会分别注册空样式、B、I 和 BI，然后在 SetFont 中按相同的家族名选择样式。正文只要调用了一个没有准备好的样式，缺字或字体回退就会表现得很像“字体注册失效”。

// 普通体、粗体和斜体是独立的字体定义，不要假设一个 JSON 能覆盖全部样式。
pdf.AddUTF8Font("report", "", "dejavu.json")
pdf.AddUTF8Font("report", "B", "dejavu-bold.json")

// 选择样式时，家族名和 style 必须与上面的注册项成对匹配。
pdf.SetFont("report", "B", 16)
pdf.Cell(0, 10, "含中文的粗体标题")

排查时可以暂时把所有输出都切回空样式。如果普通体完整而粗体缺字，问题范围就已经从“字体目录”缩小到粗体文件、粗体 JSON 或粗体字形覆盖。不要因为普通体能显示，就认为样式资源也完整。

检查字体是否真的包含目标字符

如果资源链路和样式都一致，下一层就是字符覆盖。可以把文章里实际要输出的字符按语言、符号和扩展区分组：中文正文、全角标点、数学符号、emoji、少见人名用字往往不在同一套字体的覆盖范围内。缺字只出现在少数字符时，通常更像覆盖范围问题。

处理方案有三种：换用覆盖范围更完整的 UTF-8 TrueType 字体；把不同语言片段交给各自拥有字形的字体；或者在业务层过滤、替换确实不需要输出的特殊符号。最后一种只能用于明确允许丢失信息的场景，不能把静默删除当作通用修复。

对于混排文本，建议在生成前建立一个小型字符集清单，并用它检查字体采购或打包结果。这个检查不需要运行 PDF 生成器，但能提前发现“英文样例正常、真实中文数据缺字”的差异。

子集字体最容易把字形裁掉

gofpdf 提供 UTF8CutFont，可根据字符集生成只包含指定 rune 的 TrueType 子集。它适合减小嵌入字体体积，但子集的输入必须覆盖最终正文；如果只按测试标题生成子集，生产数据里出现的新汉字就会缺字。

// cutset 必须来自最终会写入 PDF 的字符集合，而不是只取一条测试标题。
cutset := "项目报告中文标题：甲乙丙，0123456789"
subFont := gofpdf.UTF8CutFont(fullFont, cutset)

// 子集生成后还要重新生成配套的字体定义文件，再交给 AddUTF8Font 使用。
// JSON、Z 文件和子集 TTF 不能来自不同版本或不同 cutset。
_ = subFont

子集方案要特别注意配套关系：子集 TTF 变了，字体定义文件也应重新生成；发布包中不要把旧 JSON 和新字体文件拼在一起。若文章标题能显示、正文某个新字符不能显示，这一层的可能性很高。

我现在使用的缺字速查顺序

我会先把样式切回普通体，再确认字体目录和 JSON，最后才检查字符覆盖与子集。这样每一步都能缩小范围，也不会把“PDF 能生成”误当成“字体已经完整可用”。

常见追问

调用 AddUTF8Font 后还需要 SetFont 吗？

需要。AddUTF8Font 负责导入并注册，SetFont 才选择后续输出使用的家族和样式。

为什么英文正常、中文缺字？

编码可能已经是 UTF-8，但当前字体的字形覆盖不含中文；UTF-8 不会改变字体本身的字符集合。

只注册普通体可以调用 SetFont 的 B 吗？

不建议。粗体是独立样式资源，应该准备匹配的定义文件和字体文件，并按相同家族名注册。

能不能直接把缺失字符删掉？

只有在业务明确允许丢弃该字符时才可以；报告、合同或用户输入场景应优先换字体或拆分字体。