pdfmake中文PDF乱码终极指南：从字体缺失到完整解决-北京尧图网络

简介面向需要在前端项目中实现PDF导出的开发者这份资源解决pdfmake默认字体不支持中文而导致的乱码问题。包内将方正中文轮廓字体封装为JavaScript字体映射文件配合pdfmake核心库与一个可直接运行的HTML示例形成开箱即用的纯前端中文PDF导出方案即使不熟悉字体配置也能通过示例快速理解接入步骤。资源共4个文件以2个JS脚本和1个HTML页为主另含macOS系统元数据文件JS分别承担pdfmake核心逻辑与中文字体注册HTML提供完整演示环境整体压缩包仅2.36MB迁移成本低。已有1313人学习下载。资源内含可直接运行的HTML示例打开后即可在浏览器中导出无乱码中文PDF示例同时展示了字体注册、文档定义与下载触发等关键写法便于复用到合同、报表、工单等实际项目也可作为批量生成中文文档页面的基础模板。1. pdfmake 导出中文 PDF 全是方块乱码这不是玄学是字体缺字形搞导出功能的开发者多半在 pdfmake 上栽过同一个跟头英文和数字测得好好的切到中文一导出PDF 里满屏“□□□”方块运气差一点直接乱码符号。最初我也以为是编码问题把 UTF-8、BOM 声明试了个遍统统无效——后来才明白pdfmake 默认配置里带的 Roboto 字体根本不包含中文字形PDF 遇到缺字形的字符只能拿空方块替上。乱码不是字错了是字没了。这类故障常见于报表、单据、合同导出模板里只要有中文表格和签名栏基本绕不开“pdfmake 中文乱码”这个关键词。下面按我的排错顺序写先讲根因再讲字体选型、vfs 生成、前后端注册最后给一套能直接照做的快速验证流程。新手可以照命令抄作业熟手可以直接看 2.2 的根因对照和第 5 章的避坑记录。2. 为什么 pdfmake 中文乱码先分清“豆腐块”和“乱码符号”2.1 pdfmake 的字体机制PDF 不存“文字串”只存字体字形编号pdfmake 底层依赖 pdfkit 做排版和字体嵌入。你在 docDefinition 里写的中文文本会被拆分成字符后再映射成字体内部的 glyph id最后写进 PDF 的内容流阅读器打开时根据这些 id从嵌入字体里把字形画出来。这里有个关键前提字体里必须真的存在这个中文字形。pdfmake 的示例和默认配置里带的是 Roboto它的字符集只覆盖拉丁、希腊、西里尔等语系中文汉字基本查不到。字形查询失败的后果就是用该字体里的 .notdef 占位符渲染也就是你看到的空方块。明白这个机制就能解释为什么一堆“土办法”无效给文本配置 encoding、在字符串前面拼 UTF-8 BOM、把 JSON 文件另存为 UTF-8……这些操作改变的是源码层编码而 PDF 内部用的是“字体表到 Unicode 的映射”渲染结果只由嵌入字体有没有该字形决定。真正要做的是让 pdfmake 加载一款带中文字形的 TTF并在文档定义里显式指定用它渲染。浏览器里那种“缺字形自动换下一个字体”的行为在 PDF 里不存在pdfmake 也不会自动回退这就是它和 HTML 渲染最本质的差别。对使用者来说字体加载这条链路像半个黑匣子跑通之前只能靠输出结果反推。这里先提醒一个容易误踩的细节Roboto 在示例代码里通常只配了 normal 一个文件很多人以为“把 normal 换成中文字体文件就行”。实际上 pdfmake 的字体描述符有 normal、bold、italics、bolditalics 四个槽位模板里任何一处用了粗体或斜体就会去对应槽位找文件。只替换 normal 槽位遇到加粗文本照样缺字形或直接报错。这个细节后面第 4 章会展开这里先建立认知。2.2 三种表现对照表方块、乱码符号、报错分别说明什么动手改代码之前先给自己诊断一下你遇到的究竟属于哪一类。三种表现的排查方向完全不同我这里把它做成了对照表表现根因方向最可能的问题点英文数字正常中文全是“□”空方块字体缺字形仍在使用默认 Roboto或中文字体没生效中文变成“锟斤拷”“烫烫烫”这类乱码符号数据源编码损坏字符串在进入 pdfmake 前已被错误解码与字体无关运行时报错如 Font xxx does not exist字体描述符配置错误fonts 里定义的字体名、文件名与 vfs 里的键名不一致第一行的典型特征是“方块是整齐的、等宽的”说明字符已经被正确解析成 Unicode 码点只是渲染不出字形第二行的乱码则是一堆莫名其妙的中文符号这是编码转换损坏的经典产物。字符串在某种编码下被错误解码、再编码、再解码最后就变成“锟斤拷”“烫烫烫”这类东西。遇到第二种情况去折腾字体就是白费功夫应该回头检查接口返回的字符串编码、文件读取时的解码方式以及数据库连接的字符集配置。第三行最好判断报错信息里直接点名了字体名按第 4 章的注册步骤核对一遍即可。还有一种容易误判的情况导出后用某个老旧的 PDF 阅读器打开是方块换一个阅读器就正常。这种通常不是 pdfmake 的问题而是阅读器对字体嵌入方式的兼容性差异。所以后面的验证步骤里我会特别强调判断乱码前先换一个主流且较新的阅读器打开避免被工具误导。2.3 五分钟最小复现把根因钉死再动手与其反复猜不如先做一个最小页面验证。我一般会直接出一份只含三行内容的 PDF整个过程不到五分钟const docDef { defaultStyle: { font: Roboto }, content: [ English 123, 中文测试, 中文 English 混合 123 ] }; pdfMake.createPdf(docDef).download(diagnose.pdf);提示这一步先不要配置任何中文字体目的是看默认状态下问题到底长什么样。导出后打开诊断 PDF按下面规则读结果第 1 行正常、第 2 行全方块说明字体缺中文字形直接进入第 3 章第 1 行都不正常说明 pdfmake 本身加载有问题先检查库文件的引入路径和版本第 3 行英文正常、中文异常同样指向字形缺失而不是编码问题。这个测试同时排除了阅读器干扰建议用主流且较新的阅读器打开诊断文件。如果诊断 PDF 里根本不是方块而是一堆乱码符号那就要回头追数据源。我常用的定位办法是在生成 PDF 之前先把将要写入的字符串console.log出来直接看这段文本在内存里是否正确。文本到 pdfmake 手里时只剩 Unicode 码点前面任何一个环节用错了解码方式都会在这里现出原形早发现早止损。3. 准备中文字体并构建 vfs_fonts先拿到一份能用的 TTF3.1 字体选型TTF 优先留意字形覆盖和授权中文字体不是“能显示中文就行”。pdfmake 要的字体至少满足三个条件轮廓是 TrueType 格式也就是 .ttf 文件字形覆盖足够全授权允许嵌入文档。开源中文字体有很多选择常见做法是去开源字体仓库的 Release 页下载 TTF 版本。为什么特别强调 TTF因为 OTF 虽然能在操作系统里正常显示但不少 OTF 使用的是 CFF 轮廓落到 PDF 字体嵌入这条链路时和 pdfmake 底层 pdfkit 的兼容性不如 TTF 稳实测中更容易出现个别字形渲染失败或部分阅读器打开空白的情况。字形覆盖这关最容易栽跟头。精简版字库只覆盖 6763 个常用简体汉字模板里出现客户姓名、生僻地名时照样漏字形导出后又是零星方块。生产环境我一般选覆盖 GB18030 或全量 CJK 字形的字体文件缺点是体积大但换来的是无乱码没有例外项。授权方面把字体嵌入 PDF 属于文档嵌入行为但不同字体协议的条款细节不同商业系统里记得先确认能否嵌入和子集化避免交付时吃法律的后悔药。另外要提一个很容易遇到的坑系统字体目录里常见的 .ttc 是多个字体打包在一起的集合格式pdfmake 对这种格式的支持不稳定不要直接拿系统 .ttc 来注册要找单字体的 .ttf 文件。选好字体后文件名尽量用英文字母、数字、下划线不要带中文名和空格。vfs 用文件名做键来匹配字体中文文件名在部分平台和构建链路里会出现编码不一致键对不上的时候运行时就报 Font not found。3.2 用官方脚本把字体打包成 vfs_fonts.jspdfmake 在浏览器里取字体是同步行为文档一创建立刻就要拿到字体二进制数据没有时间等字体通过网络慢慢加载。官方为此提供了 build-vfs 脚本把字体 base64 编码后塞进一个 JS 对象这个对象就是 vfsvirtual file system虚拟文件系统。操作流程如下# 在已有项目里安装 pdfmake npm init -y npm install pdfmake # 把下载好的 TTF 字体放进 fonts/ 目录 mkdir -p fonts # 假设已经放入了 NotoSansSC-Regular.ttf # 用官方脚本生成 vfs_fonts.js node node_modules/pdfmake/build-vfs.js fonts/NotoSansSC-Regular.ttf vfs_fonts.js脚本做的事很简单读取 TTF 文件转成 base64 字符串拼成一个包含window.pdfMake和vfs对象的 JS 文件。生成后文件里会看到类似NotoSansSC-Regular.ttf: AAEAAAASAQAABAAg...的长字符串键名就是当初传入的文件名。这里有个很容易翻车的点文件名必须原样保留大小写和扩展名都要一致pdfmake 运行时就是拿这个字符串去 vfs 里取数据差一个字符都匹配不上。脚本也支持一次传多个字体需要同时准备常规字重和粗体字重时写法是node node_modules/pdfmake/build-vfs.js fonts/NotoSansSC-Regular.ttf fonts/NotoSansSC-Bold.ttf。另外要有个心理预期vfs 里存的是 base64 字符串JS 文件体积会膨胀到字体原体积的 1.35 倍左右这是正常现象。如果项目对前端资源体积极其敏感可以考虑把导出放到 Node 服务端做字体留在服务器上浏览器只负责发起请求。提示不同 pdfmake 版本的 build-vfs 脚本路径可能有差异如果node_modules/pdfmake/build-vfs.js不存在去 node_modules/pdfmake 目录下找带 vfs 字样的脚本原理相同。3.3 生成后先核对三件事别急着写业务代码vfs_fonts.js 生成完之后我通常会花一分钟做三个核对相当于给后面的排错省一半时间# 1. 确认体积base64 会让字体体积膨胀约 1.35 倍 ls -lh fonts/NotoSansSC-Regular.ttf vfs_fonts.js # 2. 确认文件里包含字体文件名的键 grep -o NotoSansSC-Regular.ttf vfs_fonts.js | head -1 # 3. 确认文件没有截断结尾应该是完整的 JS 对象收尾 tail -c 200 vfs_fonts.js第一步的体积比例是个很好的健康指标如果 vfs_fonts.js 明显小于 TTF 的 1.3 倍多半是脚本只读到了部分文件或者命令输出被截断了。第二步确认键名正确这一步过了第 4 章配置字体描述符时就能少一个报错。第三步防的是重定向输出时文件被截断这个问题在 Windows 环境尤其常见用 PowerShell 执行重定向后更要确认输出文件非空且结尾完整。三个核对都通过再把这个文件引入页面或打包进构建产物。4. 注册字体并让文档定义选中它配置到位才算无乱码4.1 前端浏览器注册vfs 和 fonts 描述符缺一不可浏览器端引入两个文件后通过pdfMake.fonts声明字体家族。直接给一份可改用的完整示例script srcpdfmake.min.js/script script srcvfs_fonts.js/script script // 字体家族名可以自己起但要和文档定义里的 font 保持一致 pdfMake.fonts { NotoSC: { normal: NotoSansSC-Regular.ttf, bold: NotoSansSC-Bold.ttf, italics: NotoSansSC-Regular.ttf, bolditalics: NotoSansSC-Bold.ttf } }; const docDef { defaultStyle: { font: NotoSC, fontSize: 12 }, content: [ { text: 这是中文内容不再乱码, alignment: center }, { text: 编号NO.2024-0001 } ] }; pdfMake.createPdf(docDef).download(中文报表.pdf); /scriptfonts 结构里四个槽位都要写normal、bold、italics、bolditalics。中文几乎没有斜体字形所以 italics 和 bolditalics 指回常规字重文件但前提是这些键都真实存在于 vfs 里。只配置 normal 一个键的项目模板里只要有加粗或斜体声明渲染时就可能报字体不存在。defaultStyle.font是全局开关普通文本都会走这个家族download的文件名带中文也没问题这个 API 会自己处理文件名编码。如果是 webpack/vite 这类打包构建而不是直接用 script 标签引入方式略有不同需要把 vfs_fonts.js 当模块导入再手动把 vfs 对象挂到 pdfMake 上。常见做法是这样写import pdfMake from pdfmake/build/pdfmake; import pdfFonts from pdfmake/build/vfs_fonts; pdfMake.vfs pdfFonts.pdfMake.vfs; pdfMake.fonts { NotoSC: { normal: NotoSansSC-Regular.ttf, bold: NotoSansSC-Bold.ttf, italics: NotoSansSC-Regular.ttf, bolditalics: NotoSansSC-Bold.ttf } };注意打包场景里最容易漏掉的就是pdfMake.vfs pdfFonts.pdfMake.vfs这一行漏了之后 pdfmake 手里没有字体数据创建文档时大概率直接报错或输出空内容。4.2 Node 服务端注册传文件路径不走 vfs服务端导出时不需要把字体 base64 进 JS 文件给 PdfPrinter 构造器传字体文件路径即可这是前后端实现最大的差异const PdfPrinter require(pdfmake); const fs require(fs); const path require(path); const fonts { NotoSC: { normal: path.join(__dirname, fonts, NotoSansSC-Regular.ttf), bold: path.join(__dirname, fonts, NotoSansSC-Bold.ttf), italics: path.join(__dirname, fonts, NotoSansSC-Regular.ttf), bolditalics: path.join(__dirname, fonts, NotoSansSC-Bold.ttf) } }; const printer new PdfPrinter(fonts); function exportPdf(docDef, outputPath) { const doc printer.createPdfKitDocument(docDef); doc.pipe(fs.createWriteStream(outputPath)); doc.end(); }这里的 font 值是真实文件路径所以我用path.join(__dirname, ...)基于当前模块目录拼而不是依赖进程启动时的 cwd。否则从别的目录启动服务路径就飘了导出的 PDF 会在一阵静默降级后变成乱码。我习惯在入口处加一道保险用fs.accessSync逐个验证字体文件可读启动时就把路径问题暴露出来而不是等用户导出时才看到一份坏文件。服务端的 docDef 结构和前端完全一致defaultStyle.font同样要指向这里定义的字体家族名。还要注意一个细节服务端把 PDF 生成结果返回给前端下载时字体字节已经打进 PDF 文件里了用户端并不需要安装中文字体就能正常显示所以不用担心“用户没装字体就乱码”。这也是 PDF 相比网页渲染的优势之一前提是你真的把字体嵌进去了。4.3 别漏掉页眉页脚、表格和显式 font 覆盖defaultStyle只对“没有单独写 font 的文本”生效。页眉页脚、表格单元格、以及单个文本对象里显式写了font: Roboto的地方都会用自己的字体设置你配好的中文字体覆盖不到那里。这个坑我踩过不止一次正文全部正常页眉一排方块定位了半天发现是模板初始化时写死了默认字体名。处理办法是全局搜索代码里的font:关键字把每一个显式字体设置都改成新的字体家族名。如果模板需要混排比如英文标题用一款西文字体、中文正文用中文字体就在对应文本对象上用font单独覆盖但两个家族都必须在 fonts 和 vfs 里同时注册。这里再强调一次PDF 没有字体回退机制混排时 pdfmake 不会像浏览器那样“缺字自动换字体”每个字符只能靠当前指定字体来渲染。这就是为什么模板里字体名写错一个乱码就精准出现在那一个区域其他区域看着都正常。5. 避坑乱码、空白页、体积暴涨的常见坑记录下面五条是我在多个导出项目里真实踩过的坑按现象、原因、解决三步记录方便直接对照。5.1 现象导出成功但生僻字和特殊符号还是方块原因字体本身的字形表没有覆盖这个字符。精简字库只收录常用汉字超出范围的字在字体文件里根本不存在渲染时只能退化成 .notdef 占位符也就是方块。解决换成大字库 TTF覆盖 GB18030 或全量 CJK 字形如果只是少量特殊字符可以在写入前检测该字是否在字体覆盖范围内不在则提示用户替换但根治法仍然是换字库。选型时优先看字体说明里标注的字符集范围而不是只看“支持中文”四个字。5.2 现象浏览器导出正常服务端接口导出的 PDF 乱码原因服务端代码构造 PdfPrinter 时没传中文字体描述符或者字体文件路径不对pdfmake 在找不到字体时静默降级最终用默认字体渲染中文复现出和第 2 章一样的方块现象。解决在服务端入口用fs.accessSync校验每个字体路径把字体描述符的构造抽成公共函数前后端共用同一份配置避免两套写法漂移服务端日志里出现与 Font not found 相关的字样时优先按路径问题处理别急着改字体文件。5.3 现象导出的 PDF 体积从几百 KB 涨到 20MB 以上原因中文字体单个文件通常 8 到 15MB如果 normal、bold 各自指向完整字体且没有做子集化体积就会成倍叠加部分旧版本的字体嵌入链路还会把整个字体全部写进 PDF而不是只写用到的字形。解决先检查四个描述符是否各自指向不同的大文件尽量只保留 Regular 和 Bold 两个字重再确认 pdfmake/pdfkit 版本较新较新版本默认只嵌入用到的字形仍然超标的话用子集化工具按业务常用字串预生成一份瘦身后的字体再注册。5.4 现象用 OTF 字体导出后某些阅读器打开是空白页原因OTF 的 CFF 轮廓在部分 PDF 阅读器的嵌入渲染链路里兼容性差同一份 PDF 在 A 阅读器正常在 B 阅读器空白排错时容易被误判成 pdfmake 的问题。解决把 OTF 转成 TTF 再走完整流程转换后用第 3.3 节的方法重新生成 vfs_fonts.js并同步修改描述符里的文件名避免旧文件名残留。转换工具用常见的字体处理工具即可转完记得再导出一次最小测试 PDF 验证。5.5 现象PDF 显示正常但复制出来的文字是乱码原因PDF 的显示依赖字体字形复制和搜索依赖另一套 ToUnicode 映射表。某些改造过的字体或“伪装字体”没有正确的映射信息页面看着正常复制出来却是乱码。解决换正规来源的 TTF 字体不要为了省事把一款西文字体强行注册成中文字体家族导出后用 PDF 阅读器选中一段中文复制出来粘贴到文本编辑器里看结果这是交付前最容易漏掉的验证环节。6. 快速定位三分钟判断是字体缺失还是映射错乱6.1 从“单字 PDF”开始永远是最快的分水岭当再有人拿着乱码 PDF 来找我我不会先打开他的业务模板而是先跑一个最小用例pdfMake.createPdf({ content: [中] }).download(single.pdf);单独一个“中”字如果导出后还是方块说明字体根本没生效或被错误注册问题在字体链路不在业务模板。单字正常再逐步加长文本、加粗体斜体、加表格和页眉每加一层导出一份。这种二分法比直接盯着一份二十页的报表找原因高效得多能快速把问题锁定在某个具体特性上。6.2 用 pdffonts 检查 PDF 到底嵌入了哪款字体命令行检查是最客观的手段不依赖人对阅读器的观感。Linux 系统可以用 poppler-utils 自带的 pdffonts 看字体嵌入情况macOS 安装 poppler 后也有同样的命令pdffonts output.pdf输出里会列出 PDF 内嵌字体的名称、类型、Embedded 状态emb 列。如果看到你的中文字体名且 emb 为 yes说明字体确实嵌入了如果显示的是 Roboto 或某个替代字体说明 pdfmake 配置的字体根本没被用上回头查 4.1 或 4.2 的注册步骤。Windows 上没有现成的 pdffonts 时可以用自带“字体列表”功能的 PDF 阅读器替代效果类似。6.3 前端核对 vfs 键名和描述符的一致性浏览器里调试时有随手可用的检查方式打开控制台直接看 vfs 里究竟有哪些键Object.keys(pdfMake.vfs).filter(k k.indexOf(SC) ! -1);注意如果这行返回空数组说明 vfs_fonts.js 没加载成功或键名不对如果返回了文件名再把它和第 4 章 fonts 描述符里的字符串逐个比对大小写和扩展名都不能差。6.4 我现在的固定排查顺序从那以后我每次在项目里用 pdfmake 做导出都会强制走一遍固定顺序先跑“单字 PDF”确认字体链路通再看 vfs 键名和描述符能否对上导出后用 pdffonts 验证嵌入结果最后才打开业务模板逐层加内容。字体文件更换版本后我也一定会重新生成 vfs_fonts.js绝不让旧的 base64 串滞留这一步已经救过我几次。希望这套顺序能帮你少走弯路尽早导出第一份无乱码中文 PDF。本文还有配套的精品资源点击获取

pdfmake中文PDF乱码终极指南：从字体缺失到完整解决

相关推荐

knowledge-work-plugins 插件化架构解析：用斜杠命令重塑 Claude Code 知识工作流

数学分析讲义PDF的高效用法：从预习到定理表的闭环学习法

ESP32舵机控制全攻略：PWM精度、电源隔离与平滑运动实现

更多资讯

AI大模型进化史：从Transformer到Agent，TaoToken统一Key打通调用链路

超市收银系统源码拆解：从扫码到扣库存的事务与并发实践

AI论文分析工作流实战：数据整理、信息提取、横向对比与综述生成

基于Qt的串口调试助手：集成TCP、UDP与CAN通信的通用上位机

货架空置检测实战：FCOS_HRNetV2P调优与部署全记录

机器学习分类任务全流程指南：从数据准备到模型评估

今日更新

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？