Golang生成PDF方法_gofpdf创建导出PDF教程

本文深入解析了使用 Go 语言的 gofpdf 库生成高质量中文 PDF 时最常见、最易踩坑的核心问题：从中文显示为方块的根源（未正确加载中文字体）到链接失效、表格内容截断、保存静默失败等实战痛点，逐一给出精准原因和可立即落地的解决方案——包括必须用 NewCustom 初始化、AddFont 与 SetFont 的严格调用顺序、AddLink 的页面上下文约束、MultiCell 行高与边框的协同设置，以及 Save 前强制创建目录等关键细节，帮助开发者跳出“无报错却无效”的调试陷阱，真正实现稳定、可控、所见即所得的 PDF 导出。

gofpdf.New() 初始化时字体路径没设对，PDF 里中文全是方块

gofpdf 默认不带中文字体，New() 后直接写中文会渲染成空白或方块。不是编码问题，是字体文件根本没加载。

实操建议：

• 用 gofpdf.NewCustom(&gofpdf.Rect{W: 210, H: 297}, "mm", "A4") 创建 PDF 实例，避免默认单位引发尺寸错乱
• 调用 AddFont() 前，确保 TTF 文件存在且路径可读（比如放在 ./assets/fonts/simhei.ttf）
• 必须先 AddFont("simhei", "", "assets/fonts/simhei.ttf")，再 SetFont("simhei", "", 12)，顺序错了字体不会生效
• Windows 下路径用正斜杠 /，别用反斜杠 \ —— gofpdf 不识别转义，会静默失败

AddPage() 后 AddLink() 失效，点击链接没反应

gofpdf 的链接依赖页面上下文，AddLink() 返回的 uint 只在当前页有效；如果在 AddPage() 之后才调用，链接目标页码是 0，实际跳转就失效。

实操建议：

• 所有 AddLink() 必须在 AddPage() 之后、CellFormat() 或 Write() 引用前调用
• 跨页链接要手动传入目标页码：比如第 3 页的锚点，得先在第 3 页调用 SetLink(link, 0, 3)
• 用 Write() 写带链接的文字时，第 2 个参数是 string，不是 uint——别把 AddLink() 返回值直接塞进去，要先存变量

Cell() 和 MultiCell() 渲染表格时内容被截断

Cell() 是单行固定高，MultiCell() 才自动换行；但后者默认不撑开行高，文字可能被下一行盖住。

实操建议：

• 表格场景优先用 MultiCell()，并显式设置 ln 参数：比如 MultiCell(40, 5, "长文本", "LTRB", "C", false)
• 行高不能小于字体大小的 1.2 倍，否则第二行文字会被裁掉——试过 5 不行就改 6，别硬扛
• 边框线宽影响可用高度：SetLineWidth(0.2) 比 0.5 更安全，粗线会吃掉更多垂直空间
• 中文标点（如句号、逗号）在某些字体里宽度异常，导致换行错位，加个 str := strings.ReplaceAll(str, "。", "。 ") 微调空格能缓解

Save() 到磁盘失败但无错误提示

Output() 和 WriteTo() 都可能静默失败——比如目录不存在、权限不足、路径含非法字符，返回 nil error 但文件没生成。

实操建议：

• 别只信 err == nil，保存前先 os.MkdirAll(filepath.Dir(path), 0755)
• 用 WriteTo(filename string, perm os.FileMode) 替代 Output()，它明确接受权限参数，出错也更容易定位
• Windows 下路径含中文没问题，但不要用 ~/ 或环境变量，gofpdf 不解析 shell 路径缩写
• 调试时加一句 data, _ := pdf.Output(); fmt.Printf("PDF size: %d bytes\n", len(data))，至少确认数据生成成功

字体加载和路径处理是最常卡住的地方，其他问题大多能靠打印字节长度和检查返回值提前暴露。别假设 PDF 生成是“黑盒成功”，它只是不报错，不代表做对了。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Golang生成PDF方法_gofpdf创建导出PDF教程》文章吧，也可关注golang学习网公众号了解相关技术文章。