Go 项目里用 PDF 生成报告、发票、订单的时候最让人头疼的就是中文乱码——明明英文和数字显示得好好的中文进去就变空白方块、乱码字符严重的时候直接抛异常。我用 Go 写 PDF 处理模块踩过不少坑也梳理了一些真正能落地的方案这篇就完整聊一下Go 生成 PDF 要支持中文核心到底要处理哪些问题每一步怎么选。1. 先想清楚为什么 Go 生成 PDF 默认“不认识”中文1.1 中文显示失败到底卡在哪很多刚入场的开发者会下意识觉得是“编码问题”把乱码简单归因于没转 UTF-8然后折腾各种字符串编码转换结果折腾半天还是失败。实际上这里有两个层面的原因而且都比编码更“底层”。第一层是字体缺失。PDF 文件不像 Word 那样能自动调用系统字体来渲染文本它需要在文件内部把字体资源定义好。Go 生态中常用的 PDF 生成方案默认内置的都是标准 PDF 字体比如 Helvetica、Times、Courier 这些。这类字体由 PDF 阅读器统一提供字符集覆盖范围很有限只支持拉丁文、数字、基础符号根本没有中文字形。所以哪怕你把中文字符串以 UTF-8 正确塞进 PDF 内容流阅读器也不知道该用什么字形去渲染输出来的自然就是空白或方块。第二层是字符映射和编码机制不到位。PDF 的文本对象需要通过字体对象的 Encoding 或 ToUnicode 映射关系把字符串中的每个字符对应到字形索引。中文字符如果用普通的单字节编码表去映射必然会出现错位、偏移最终渲染出乱码。更麻烦的是中文通常不是“一个字节一个字形”而是多变节字符没有正确的 CID 映射机制阅读器根本无从解析。简单类比一下你给一个外国人一张商品清单上面写的全是中文他看不懂不是因为清单本身写错了而是他和清单之间缺了一个“翻译规则”。PDF 阅读器和中文文本之间缺的“翻译规则”就是字体文件和字符映射表。了解了这一点就知道方案的核心不是字符串编码转换而是字体处理和 PDF 内部资源注册。1.2 字体方案选型不是“选一个中文字体”那么简单既然问题是字体那就给 PDF 增加中文字体。但这里要做的选择比想象中更多而且直接影响后续所有代码的写法。Go 生态里生成 PDF我实际用过两条路线。一条是纯 Go 实现的第三方库比如 gofpdf、fpdf 这些偏底层的库直接控制 PDF 对象、页面、字体资源另一条是调用外部渲染组件通过模板或者自定义脚本把 HTML 转换成 PDF。后一条路线虽然前端样式友好但要引入额外的运行时依赖部署复杂度会上去。我更推荐第一类纯 Go 库理由有三个一是跨平台部署方便编译产物里没有外部进程调用二是字体嵌入逻辑是自己控制的对中文字体加载方式一目了然三是排查问题可以直接看 PDF 结构不存在中间层干扰。接下来我讲的都是基于这类库的实操。字体文件的选择也有讲究。市面上的中文字体很多但用于 PDF 嵌入时要考虑几点字体文件是否允许嵌入授权协议、是否有足够大的字符集、文件体积能不能接受。常见的像一些开源中文字体比如思源黑体系列字符覆盖全面、授权宽松很适合做基础字体套件。如果你手头有商业授权的字体文件也可以用但自己要看清楚授权条款允不允许嵌入和分发。字体加载方式上大多数纯 Go PDF 库支持从文件路径或者字节数组加载 TTF 字体。字节数组加载在实际开发中很实用比如字体放在服务器某个目录、数据库字段或嵌入的静态资源里直接读成[]byte再注册灵活性更高。我一般会在项目里用一个 FontService统一管理字体资源的读取和注册避免每个业务模块各搞一套。2. 核心细节拆解字体、坐标、换行一个都不能漏2.1 字体加载与嵌入是第一个关键点用 gofpdf 类库来实现时加载中文字体的标准操作大概是这样的pdf : gofpdf.New(P, mm, A4, ) fontFile, err : os.ReadFile(path) if err ! nil { log.Fatal(err) } pdf.AddUTF8FontFromBytes(NotoCN, , fontFile)这段代码看着简单但几个细节要注意。首先是字体名字不要乱起这个名称是你在后续 SetFont 时用来索引字体的标签我建议就写字体简称比如 NotoSansCN、SourceHanSansCN 之类保持统一。其次AddUTF8FontFromBytes第二个参数是样式如果是普通体就留空字符串如果你还想嵌入粗体或斜体需要分别加载另一个字体文件并且用 B、I 这样的样式标识去区分。真正的关键点是“嵌入”这一步。通过字节数组加载字体时库会自动把字体数据写入 PDF 的字体资源对象中生成后的 PDF 无论在哪台机器上打开都能正确显示中文不依赖目标机器有没有安装中文字体。这个特性特别重要因为 PDF 文件一旦被分发出去你完全没法控制接收方电脑的系统环境。嵌入字体也有代价文件体积会变大。一个思源黑体的 OTF 文件可能在 8MB 到 20MB 左右直接嵌入生成的 PDF 会显著膨胀。实际生产环境中如果生成的是多页报表每一页用到的字体会被复用体积增加一次即可但如果你每个页面都重新加载一个不同名字的字体就可能导致同一字体被嵌入多次文件体积翻几倍。所以我建议在全局只注册一次字体对象整个 PDF 生命周期复用。2.2 文本绘制与坐标系别让文字飞出页面加载完字体后画文本的 API 是SetFont加Cell或者Text。但这块有个非常容易踩坑的坐标体系问题。PDF 的坐标系一般以页面左上角为原点x 向右增长y 向下增长但也有库是以左下角为原点。go 生态里常见的实现比如 FPDF 派生的库通常遵循“页面顶部为 y 起点”的直觉式坐标系这点还算友好。不过真正容易出问题的是文本基线baseline的处理——Text方法画字符串时你定的坐标是文本的基线位置还是顶部位置不同库定义不一样。我在实践中发现Cell方法更可控因为它会把给定高度内的文本按单元格规则对齐。文本绘制还有个容易被忽略的问题中文字符串和英文字符串混排时宽度判断差异巨大。一个全角中文约占两个拉丁字符的宽度而且不同字体里中文字符的宽度还可能略有差异。如果你用对齐到右边或者居中的方式排列算错宽度文字就会溢出单元格、重叠到其他区域或者被截断。解决宽度问题的基本思路是不要自己猜字符数量而是用库提供的文本测量方法去算。go 生态里的 PDF 库一般都有GetStringWidth或者类似方法传入字串和当前字体就能拿真实渲染宽度。拿到宽度后再计算坐标位置不容易出错。我之前写过一段通用代码专门处理“标题居中”str : 中文报告标题 pdf.SetFont(NotoCN, , 20) w : pdf.GetStringWidth(str) pdf.SetX((210 - w) / 2) pdf.Cell(w, 10, str)这里 210 是 A4 宽度单位毫米。先量出字符串宽度然后计算出让文本居中的起始 x 坐标。这个方法应对中英文混排也很靠谱因为宽度是实际测量的不依赖经验值。2.3 自动换行与文本测量中文和英文的宽度逻辑完全不同生成多行文本时很多新手直接调用Cell循环换行结果要么文字不换行被截掉要么行间距不对。更合适的方案是使用MultiCell方法它支持给定矩形区域宽度后自动换行也能指定行高、对齐方式。但MultiCell对中文字体的要求比较高它内部依赖文本测量和断行算法。如果你的字体没有注册成功或者字符串被错误处理常见的表现就是整段文字变成长长一坨挤到页面边缘或者干脆渲染成几个孤立字符。使用MultiCell时我习惯这样写leftMargin : 20.0 rightMargin : 20.0 pageWidth : 210.0 cellWidth : pageWidth - leftMargin - rightMargin pdf.SetLeftMargin(leftMargin) pdf.SetRightMargin(rightMargin) pdf.SetFont(NotoCN, , 12) pdf.MultiCell(cellWidth, 7, 这里是一段需要自动换行的中文内容如果内容足够长就会被拆成多行显示。, , L, false)这句代码里cellWidth是内容区宽度7是每行高度单位毫米L表示左对齐false表示不做边框。通过调节行高参数你可以控制行间距。实际生产里行高通常要略大于字体本身高度让中文字符在行内有呼吸空间。文本测量还有一个绕不开的问题PDF 标准本身不包含“字符级换行”规则中文不像英文有空格可以作为断行点。所以库的自动换行逻辑能不能正确处理中文很大程度依赖它内部是否对 CJK 字符有特殊处理。用 go 生态的成熟库时只要字体是 UTF-8 注册的、文本是合法 UTF-8 字符串自动换行基本可用。但如果你的库太冷门或者封装不全就可能需要自己写断行逻辑——这个我建议不要轻易尝试因为中文标点、全角半角混排的断行规则非常繁琐自己实现很容易出现标点悬挂问题。3. 一份可直接“抄作业”的中文 PDF 生成代码3.1 环境准备与依赖下面这份代码我用 gofpdf 库做实现它是最经典的纯 Go PDF 库之一API 稳定、文档全、社区用得多。在 Go 模块里引入依赖go get github.com/jung-kurt/gofpdf/v2字体文件方面我用一个开源的思源黑体子集文件文件名为sourceHanSansCN-Regular.otf放在项目的assets/fonts/目录下。如果你手头没有现成字体文件可以到开源字体仓库下载思源黑体的 TTF 版本注意别下载成 OTF 格式导致部分库不支持不过新版本库对两种格式都有支持。如果你不确定格式兼容性加载时留意日志出现“unsupported font format”就换格式。3.2 完整代码示例与输出说明下面是一个生成“中文月度销售简报”的完整代码包含中文标题、表格内容、多行文本和页脚基本覆盖了日常 PDF 报告的核心场景package main import ( fmt log os time github.com/jung-kurt/gofpdf/v2 ) func main() { // 1. 创建 A4 纵向页面 pdf : gofpdf.New(P, mm, A4, ) // 2. 加载中文字体 fontBytes, err : os.ReadFile(assets/fonts/sourceHanSansCN-Regular.otf) if err ! nil { log.Fatalf(读取字体文件失败: %v, err) } pdf.AddUTF8FontFromBytes(CN, , fontBytes) // 3. 页头和标题 pdf.AddPage() pdf.SetFont(CN, , 16) pdf.SetTextColor(30, 30, 30) title : 2025年6月销售简报 titleW : pdf.GetStringWidth(title) pdf.SetX((210 - titleW) / 2) pdf.Cell(titleW, 12, title) // 4. 日期信息 pdf.SetFont(CN, , 10) pdf.SetTextColor(80, 80, 80) dateStr : 生成时间: time.Now().Format(2006-01-02 15:04) pdf.SetX(20) pdf.Cell(80, 8, dateStr) // 5. 表格内容 pdf.SetFont(CN, , 11) pdf.SetFillColor(245, 245, 245) pdf.SetTextColor(20, 20, 20) headers : []string{产品类别, 销售额, 环比增长} rows : [][]string{ {智能硬件, 1,280,345, 12.5%}, {企业服务, 868,200, 8.3%}, {内容订阅, 642,150, -2.7%}, } tableLeft : 20.0 colWidths : []float64{50, 60, 40} rowHeight : 9.0 headerY : 60.0 // 表头 x : tableLeft for i, h : range headers { pdf.SetX(x) pdf.CellFormat(colWidths[i], rowHeight, h, 1, C, true, 0, ) x colWidths[i] } pdf.Ln(-1) // 数据行 for _, row : range rows { x tableLeft for i, cell : range row { pdf.SetX(x) pdf.CellFormat(colWidths[i], rowHeight, cell, 1, C, false, 0, ) x colWidths[i] } pdf.Ln(-1) } // 6. 备注区域 pdf.SetY(110) pdf.SetFont(CN, , 10) contentW : 210 - 20 - 20 note : 备注本月智能硬件受到新品发布会带动销售额环比稳步提升。 企业服务续费率保持稳定内容订阅略受季节性因素影响。 以上数据来源于内部经营分析系统仅供管理层决策参考。 pdf.SetLeftMargin(20) pdf.MultiCell(contentW, 6, note, , L, false) // 7. 输出文件 outputPath : monthly_sales_report.pdf err pdf.OutputFileAndClose(outputPath) if err ! nil { log.Fatalf(生成 PDF 失败: %v, err) } fmt.Println(PDF 已生成:, outputPath) }执行后你会得到一个monthly_sales_report.pdf文件里的中文标题、表格、备注全部正常渲染可以直接发给别人阅读不需要对方本机安装中文字体。3.3 代码逐段解读这段代码看起来长但每个环节都是刚需我拆开说几个容易被忽略的细节。首先是AddUTF8FontFromBytes(CN, , fontBytes)。这里的 CN 是字体标识是后面文本绘制共同依赖的索引。如果你需要粗体就需要再加载一份粗体字体文件并用AddUTF8FontFromBytes(CN, B, boldFontBytes)这样后续SetFont(CN, B, 12)就能调用粗体字形。常用于标题加粗省去手动伪造加粗效果。然后是pdf.SetX((210 - titleW) / 2)。这里 210 是 A4 宽度mm减掉字符串宽度再除以 2得到的是标题起始 x 坐标。重点是我先调用了GetStringWidth测量出实际渲染宽度避免标题视觉上偏离中心。这个操作在中文场景里尤其重要因为中文标题长度不能靠英文字符数推算。CellFormat方法里的参数依次是宽度、高度、文本、边框样式、对齐方式、是否填充、链接地址、备用链接。表格场景里边框样式用 1表示四边都有框线对齐方式用 C 居中填充参数true表示填充背景色配合SetFillColor使用。其中链接参数基本用不上传空字符串就好。备注区域的MultiCell调用中contentW计算方式是页面总宽度减去左右边距这样文本会限制在内容区内自动换行。如果你把contentW设置成整个页面宽度文字就会贴着页面边缘流出观感很差。最后关于输出文件名代码里用的是英文字符monthly_sales_report.pdf这是刻意为之。如果输出文件名带中文某些系统或浏览器下载时会因为路径编码或者 Content-Disposition 头处理方式不同出现文件名乱码或者打不开的情况。更稳妥的做法是生成英文文件名在业务层另存一份映射关系。4. 常见问题与排查技巧实录4.1 乱码现象速查表我在实际开发中遇到过好几种“乱码”它们的成因和解决办法差别较大整理成速查表方便你对照排查现象真正原因处理方式中文全部显示为空白方块字体未嵌入或字体不支持该字形确认字体文件加载成功检查字体字符集覆盖范围中文显示为田字格阅读器找不到内嵌字体回退到系统字体失败检查 PDF 字体资源是否真的写入了尝试更换字体注册方式中英混杂时中文正常、数字变成奇怪样式字体注册顺序不对数字被映射到其他字形检查 SetFont 后的字体索引确保中文字体包含基础拉丁字符生成 PDF 时直接报错“undefined font”字体注册名和 SetFont 字体名不一致检查 AddUTF8FontFromBytes 第一个参数和 SetFont 第一个参数是否一致单行中文输出正常多行中文全部堆在一行没使用 MultiCell或 MultiCell 宽度参数不正确改成 MultiCell传入合理的矩形区域宽度中文标题居中失败左偏或右偏用字符数估算宽度没实测渲染宽度用 GetStringWidth 测量后计算坐标这张表里我遇到频率最高的是前两类。空白方块通常意味着字体嵌入不生效田字格则往往是阅读器在字体资源里找不到可用的字形映射。解决这两类问题最直接的办法是生成 PDF 后用 PDF 分析工具打开查看文字对象引用的字体名称是否出现在字体资源列表里。如果在列表里继续检查字体对象有没有嵌入 FontFile 子流如果没有回过去看注册步骤。4.2 字体文件格式与体积的坑字体文件格式这块我最初用 OTF 格式踩过一次坑。项目中下载的字体是.otf某些 PDF 生成库内部对 CFF/PostScript 轮廓的支持不完整结果就是注册成功了画出来的字全是方块。后来换成同字体的 TTF 版本问题立刻消失。我的建议是优先选择 TTF 格式的开源中文字体兼容性最稳如果项目里只有 OTF那就先在本地跑一个小样例验证库的支持情况再继续。文件体积也要提前评估。之前一个报表项目里因为页面很多、字体又加载了好几个变体生成的 PDF 动辄几十 MB给用户发出去基本没法预览。后来我做了两个优化一是整份文档只注册一次字体不重复嵌入二是把多字体精简为常用的一两个家族减少 PDF 内部字体对象数量。经优化同样内容的 PDF 从 28MB 降到 6MB 左右体感流畅很多。如果你对体积有更极致的要求可以考虑做字体子集化只嵌入文档中用到的那些字。但字体子集化在纯 Go 生态里能用的工具不多而且会引入额外依赖和构建复杂度。绝大多数场景下把字体资源一次性嵌入、避免重复加载就够用了。4.3 文本内容里藏着的“隐形炸弹”除了字体和体积文本内容本身也可能让 PDF 生成失败或渲染异常。最常见的三个隐性问题控制字符、特殊标点、超长无换行文本。控制字符是指字符串里包含\n、\r、\t之外的不可见字符比如\x00、\x1a等。这些字符进入 PDF 内容流后轻则渲染位置偏移重则让阅读器解析出错。我遇到的真实案例是业务备注里混入了空字符生成的 PDF 在某个阅读器里直接打不开。排查方法也不难生成 PDF 前遍历字符串去掉小于 0x20 的字符保留标准换行制表符。可以用一段很小的过滤函数处理。特殊标点主要说的是全角引号、全角括号、竖排标点等。大部分中文字体都带这些字形但如果你混合使用了不同字体——比如英文数字用 Helvetica、中文用思源黑体——标点字体切换就可能引发宽度抖动和显示错位。解决方案是统一用一个覆盖中英文的字体让标点也走同一套字形映射。超长无换行文本比如一大串连续字母或数字组成的订单号长度超出了单元格宽度又没有合适的断点库的换行算法就会把它强制挤成超长行直接溢出页面边界。处理方式是在业务层对这类文本做人工分段或者用MultiCell配合自动断行规则再不行就按照宽度阈值手动插入软换行。4.4 字体缓存与并发生成 PDF 的隐患如果你的服务是在 Web 后端处理 PDF 生成请求并发问题也要提前考虑。字体文件通常在每次生成时都读一遍如果请求量大磁盘 I/O 压力会起来。我的做法是在服务启动时把字体字节数组一次性加载到内存用全局变量存起来生成 PDF 时直接从内存传给AddUTF8FontFromBytes省去重复读文件的开销。但这里要注意并发安全这里的字体字节数组本身是只读的多个 goroutine 同时读取同一个[]byte是安全的而 PDF 库实例不要共享每个请求创建自己的gofpdf.Fpdf对象用完即关。我见过有人图省事把Fpdf对象存到全局结果出现并发写页面对象导致 PDF 结构损坏生成出来的文件时而打不开时而乱码。还有一个容易被忽略的点OutputFileAndClose会把文件直接写入磁盘如果你的服务运行在容器环境下要确认输出目录可写。更优雅的方式是用Output(buf)输出到bytes.Buffer再统一交给上层处理——比如写入对象存储或者直接作为 HTTP 响应内容返回避免产生临时文件占用磁盘。最后分享一个小技巧我在多次实践里总结出一个小经验注册中文字体时尽量同时注册粗体变体。哪怕当前项目里没用粗体未来排版需求起来的时候只需在现有代码里加一行SetFont(CN, B, 14)就能实现标题加粗不用回头改字体加载逻辑。再有一个就是生成后必做的验证动作每次生成完 PDF不要只看缩略图要用 PDF 阅读器搜索里面的中文关键词确认能正确查找和复制。如果复制出来的中文字符乱码说明 ToUnicode 映射有问题PDF 虽然“看着正常”但对用户不友好——报告类文件经常要摘录内容复制功能不工作会让人直接怀疑文件质量。说实话Go 生成 PDF 支持中文原理不复杂但细节密度很高。把字体加载、文本测量、自动换行、体积控制这几件事想清楚代码写顺报告的产出效率会有质的提升。希望这篇能帮你少走点弯路。