Go gofpdf 怎样嵌入UTF8字体输出中文PDF

用 Go 生成 PDF 时，英文示例往往直接使用 Helvetica 一类核心字体；一旦文本里出现“中文发票”“项目说明”或其他 CJK 字符，真正的问题就变成了字体资源是否覆盖这些字符，以及 gofpdf 能否找到对应的字体定义。Go gofpdf 输出中文 PDF 的做法是：准备覆盖中文的 UTF-8 TrueType 字体，把字体文件与定义文件放在字体目录，调用 AddUTF8Font 注册，再用 SetFont 选择字体。

官方地址：https://pkg.go.dev/github.com/jung-kurt/gofpdf

本文按 gofpdf 官方文档的资源边界给出一个最小示例。示例里的字体文件名是占位名，实际项目应替换成自己准备并确认字符覆盖范围的字体。

先分清核心字体和 UTF-8 字体的边界

Courier、Helvetica、Times 和 ZapfDingbats 属于 PDF 核心字体，调用 SetFont 就能使用；它们不是“任意文字都能显示”的万能字体。中文场景应改用 UTF-8 TrueType 字体，例如项目准备好的 Noto Sans SC 一类字体，并让字体真正覆盖正文需要的字符。

gofpdf 官方文档把资源拆成三层：原始 TrueType 字体、由工具准备的字体定义文件，以及 New 第四个参数指定的字体目录。目录只要有一层路径不一致，注册时就可能出现找不到字体定义文件，或者生成结果缺字。

如果使用的是非 UTF-8 TrueType 或 Type1 字体，官方文档建议先通过 MakeFont 或随包提供的 makefont 工具生成定义文件；如果使用 UTF-8 TrueType 字体，则优先沿着 AddUTF8Font 或 AddUTF8FontFromBytes 这条 API 路径处理。两条路径不要混成“改一个字体名就能显示中文”。

准备字体文件和 gofpdf 定义文件

先约定一个清晰的目录，例如：

project/
├── fonts/
│   ├── NotoSansSC-Regular.ttf
│   └── NotoSansSC-Regular.json
└── main.go

这里的 JSON 不是随手写的配置，而是由 gofpdf 认可的字体定义工具生成的资源。官方文档说明，字体定义 JSON 以及嵌入 PDF 时需要的字体文件，都必须位于字体目录；调用时传入的字体资源名还要和实际生成的定义文件保持对应。

如果字体文件很大，或者应用希望把资源编译进程序，也可以研究 AddUTF8FontFromBytes。它接收 JSON 字节和压缩字体字节，适合把字体资源交给打包流程统一管理；但它没有改变“字体必须覆盖中文字符”的前提。

# 进入项目中的 makefont 目录，先构建字体定义工具
cd path/to/gofpdf/makefont
go build

# 根据项目选用的编码描述生成字体定义；路径按实际目录调整
./makefont --embed --enc=../font/cp1252.map --dst=../font ../font/calligra.ttf

上面的命令是官方文档展示的非 UTF-8 字体生成思路；中文 UTF-8 字体不应机械套用 cp1252 映射。关键是选对字体路径、定义文件格式和字符覆盖范围。

用 AddUTF8Font 注册，再交给 SetFont 输出

完成资源准备后，创建 PDF 时把字体目录传给 New，再注册一个应用内字体族名。注册成功后，后续文本写入只认这个字体族名和样式，不需要每次重复传字体文件。

package main

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

func main() {
	// 字体目录保存 TrueType 文件和 gofpdf 需要的字体定义文件。
	pdf := gofpdf.New("P", "mm", "A4", "fonts")
	pdf.AddPage()

	// 注册覆盖中文的 UTF-8 字体；样式为空表示常规字重。
	pdf.AddUTF8Font("noto", "", "NotoSansSC-Regular.ttf")
	// 注册之后用族名选择字体，不要继续使用只覆盖英文的核心字体。
	pdf.SetFont("noto", "", 14)
	pdf.MultiCell(170, 8, "中文 PDF 标题与正文", "", "L", false)

	// 输出失败时保留错误，让调用方知道 PDF 没有完整生成。
	if err := pdf.OutputFileAndClose("中文示例.pdf"); err != nil {
		panic(err)
	}
}

这里最容易忽略的是第四个参数 fonts。它是运行进程看到的字体资源目录，不是项目说明里的任意目录名；如果程序从其他工作目录启动，建议改用明确的配置路径，或调用 SetFontLocation 统一设置。

常见问题：为什么注册后仍然是空白或缺字

另外，字体资源通常会显著增大 PDF。可以先只选择需要的字重，并把字体目录纳入部署包；不要为了压缩体积而删除定义文件或把字体替换成不覆盖中文的核心字体。

结论与两个延伸问题

Go gofpdf 嵌入 UTF-8 字体输出中文 PDF，核心顺序可以压缩成三句话：准备能覆盖中文的 TrueType 字体；让定义文件和字体文件处于 gofpdf 能找到的字体目录；调用 AddUTF8Font 注册后，用同一个族名交给 SetFont。如果资源需要内置到程序，再考虑 AddUTF8FontFromBytes，但字符覆盖和资源对应关系仍然不能省略。

可以只调用 SetFont("Helvetica", "", 14) 输出中文吗？
不建议。核心字体主要解决通用 PDF 字体场景，中文是否能显示取决于字体本身是否包含目标字符；稳定做法是准备合适的 UTF-8 TrueType 字体。

为什么 AddUTF8Font 看起来成功，结果还是缺字？
优先确认字体实际包含这些字符，再确认注册后的族名确实传给了 SetFont，最后检查字体目录和定义文件是否来自同一套资源。