简介中文用户在浏览器中导出PDF时常遇到乱码根源在于PDF生成库的默认字体不支持中文字符集。方案以pdfmake为基础提供一套开箱即用的中文PDF无乱码导出方案适合前端开发人员、文档系统维护者以及需要在网页端生成中文文件的技术人员。压缩包内共四个文件体积约2.36MB主要包含pdfmake的核心库文件、支持中文显示的方正字体数据文件以及一个可直接运行的HTML演示页面其中另有系统辅助文件不影响正常使用演示页面在浏览器中即可完成中文PDF生成与下载无需服务端或复杂构建环境介入。目前已有1313人学习下载。对于正在排查中文导出乱码问题的实施者而言这套简洁可运行的示例包能够快速验证方案的完整流程也可将字体数据与核心库提取出来直接迁移到实际项目中作为集成的起点。1. 中文PDF导出不是改个字体名的事pdfmake的乱码根源与解决思路pdfmake 是前端圈子里比较常见的 PDF 生成库用 JSON 定义文档结构就能输出 PDF。但只要你往文档里放一段中文默认渲染出来就是一个个方框或者干脆空白。很多第一次用的人会想当然地把font设置成SimSun、微软雅黑结果一点变化没有。原因很简单pdfmake 不会去读你电脑里装了哪些中文字体它只认自己内置的虚拟字体文件vfs里注册过的字体默认的 Roboto 根本没有中文字形。本文不绕弯子直接给出一条把中文 TTF 字体加工成 pdfmake 可用格式、配置后导出无乱码中文 PDF 的完整路径同时把几个容易翻车的细节点出来。适合正在被中文乱码问题卡住的前端开发者和做 Node.js 服务端 PDF 导出的工程师。2. 先搞懂pdfmake的字体机制vfs、字体族与中文映射2.1 为什么默认字体下中文全是方框pdfmake 在设计上把文本渲染所需的字体文件单独抽象出来。浏览器中运行 pdfmake 时它不会调用操作系统的字体管理器而是通过一套名为“虚拟文件系统”Virtual File System简称 vfs的机制把字体文件以 base64 字符串的形式嵌入到 JS 文件里。默认情况下pdfmake 自带 Roboto 字体的 vfsRoboto 只有拉丁字母、数字和少量符号的字形所以遇到中文字符时字体渲染引擎找不到对应的 glyph最终只能画出占位的方框tofu。我们可以把这个机制理解成一个黑匣子pdfmake 拿到文档定义后会把每个文本节点按字体属性去 vfs 里查字形。查不到就用一个缺省的重合框来代替。这个过程的直接表现就是“中文全变方块”。这不是 pdfmake 的 bug而是字体资源没接进去的必然后果。// 错误示范只是改了字体名但 vfs 里根本没有这个字体 const docDefinition { content: [{ text: 这是一段中文, font: SimSun }], defaultStyle: { font: SimSun } }; pdfMake.createPdf(docDefinition).download(wrong.pdf);这段代码在运行时不会报错但生成的 PDF 中文仍然是方框。原因在于font字段只是指定了字体族的名字pdfmake 会拿着这个名字去注册表里找对应的字体数据。默认注册表里只有 RobotoSimSun这个名字没有任何字号数据与之关联所以降级回 Roboto中文照样没有字形。这类问题往往在人工查看 PDF 时才暴露而且在控制台里不一定有警告。2.2 自定义字体三步TTF转vfs、注册、声明默认样式要让 pdfmake 真正支持中文需要完成三次对接。第一步把中文字体文件TTF 或 OTF转成 base64 字符串并写进一个 vfs 文件。常见做法是写一个 Node.js 脚本读取字体文件用fs.readFileSync转 base64再拼出形如this.fontName base64字符串的 JS 对象。这个文件通常取名为vfs_fonts.js。第二步在应用启动时把这份 vfs 注册给 pdfmake。在浏览器中可以直接给pdfMake.vfs赋值如果是在 Node.js 中则需要在引入 pdfmake 之前或之后手动挂载。注册的 key 要和后续字体定义中的名字一一对应。第三步在文档定义的defaultStyle.font中指定你注册的字体族名例如HuaWenHeiTi。这一步完成后不需要在每个 text 节点重复指定font整份文档的中文都会走这个字体族。// 注册 vfs 的典型写法 import * as pdfMake from pdfmake/build/pdfmake; import * as pdfFonts from pdfmake/build/vfs_fonts; // pdfFonts 的默认导出结构是 { vfs: { Roboto-Regular.ttf: ... } } // 我们自定义 vfs 之后覆盖掉这个默认 vfs pdfMake.vfs myVfs; // myVfs 就是第一步生成的字体映射对象 const docDefinition { content: [ { text: 这是一段中文, fontSize: 14 }, { text: 第二行带粗体和颜色, bold: true, color: #333333 } ], defaultStyle: { font: MyChineseFont, fontSize: 12 } }; pdfMake.createPdf(docDefinition).download(correct.pdf);这里需要解释两个关键点。pdfMake.vfs本质上是一个普通对象key 是字体文件名value 是 base64 字符串。pdfmake 在渲染时会把font字段对应的字体族名通过内部维护的字体映射表去找到具体的字体文件再从 vfs 中取出 base64 解码为二进制字形数据。myVfs如果来自我们自定义的vfs_fonts.jskey 必须与字体映射表中声明的文件名一致。同时如果你在同一份文档里需要粗体还要额外注册一个粗体字形文件并且让字体映射表中的bold属性指向它否则文字虽然定义了bold: true实际渲染出来的仍然是普通字重。字体映射表通常这样声明pdfMake.fonts { MyChineseFont: { normal: MyFont-Regular.ttf, bold: MyFont-Bold.ttf, italics: MyFont-Italic.ttf, bolditalics: MyFont-BoldItalic.ttf } };注意key 名MyChineseFont会用于文档定义中的font字段四个属性分别对应正常、粗体、斜体、粗斜体。如果只注册了normal那么遇到bold样式时 pdfmake 会回退到 normal 渲染视觉上只是没有加粗不会报错。这属于“隐性降级”很容易被忽略。3. 把中文TTF字体转成pdfmake可用格式工具链与命令行实战3.1 字体文件选型中文字体体积与兼容性取舍中文 TTF 字体通常比拉丁字体大很多动辄 10MB 到 20MB。原因很简单常用汉字有几千个每个汉字都需要独立的轮廓数据。把这 10MB 转成 base64 后字符串会长约 13MB 到 27MB生成的vfs_fonts.js会非常大。浏览器加载这个文件会有明显延迟Node.js 服务端占用的内存也会上升。所以选字体时第一原则不是好看而是体积可控和版权可用。如果只是做内部系统导出的报表推荐使用开源中文字体例如思源黑体Source Han Sans的单个子集 TTF或者更轻量的文泉驿微米黑。这些字体在常见字号下清晰度足够而且授权允许商用和再分发。如果你处理的是财务单、合同这类需要精确对齐小数字的场景可以优先考虑思源宋体的子集版。另一个取舍是是否需要完整字库。很多业务场景只用到几百个汉字但 PDF 生成库不会动态裁剪字形所以完整字库的体量是刚性的。如果输出对象只是固定模板可以考虑用字体子集工具把用到的字符裁剪成一个几百 KB 的小 TTF这样vfs_fonts.js能控制在 1MB 以内。常见做法是使用官方fonttools的pyftsubset命令按文本文件提取字符集。# 用 fonttools 对思源黑体做子集化只保留文件里的字符 pyftsubset SourceHanSansSC-Regular.otf \ --text-filerequired_chars.txt \ --output-fileMyFont-Regular.ttf \ --flavorttf这段命令里--text-file指向一个包含所有可能出现的汉字的纯文本文件比如从数据库用户表里手工收集的姓名字符、地址常用字等。--flavorttf表示输出 TTF 格式因为 pdfmake 对 OTF/CFF 的支持不如 TTF 稳定。子集化之后的字体文件通常只有 300KB 到 800KB加载速度会有非常明显改善。注意子集化必须确认业务未来不会出现新汉字否则新字符会被漏掉PDF 中会出现个别方框这种事故比全篇乱码更隐蔽。3.2 vfs_fonts.js生成过程详解vfs_fonts.js 的本质是一个 JS 文件里面定义了一个全局对象对象属性是字体文件名属性值是 base64 字符串。官方工具通常会生成形如pdfmake.vfs {...}或者this.pdfMake.vfs {...}的结构。我们这里用一个更直接的方式写一个脚本build-vfs.js把字体目录里的所有 TTF 读出来逐个转成 base64最后拼装成一个vfs_fonts.js。const fs require(fs); const path require(path); const fontsDir path.join(__dirname, fonts); const outFile path.join(__dirname, vfs_fonts.js); const fontFiles fs.readdirSync(fontsDir).filter(file file.endsWith(.ttf)); const vfs {}; fontFiles.forEach(file { const filePath path.join(fontsDir, file); const base64 fs.readFileSync(filePath).toString(base64); vfs[file] base64; }); const content const vfsFonts JSON.stringify(vfs, null, 2) ;\n if (typeof module ! undefined) { module.exports vfsFonts; }\n; fs.writeFileSync(outFile, content, utf8); console.log(生成完成${fontFiles.length} 个字体vfs_fonts.js 大小 ${(fs.statSync(outFile).size / 1024 / 1024).toFixed(2)} MB);脚本的逻辑很直白读取fonts目录下所有.ttf文件用readFileSync().toString(base64)转码然后组装成一个 JSON 对象写入vfs_fonts.js。module.exports那行是为了在 Node.js 里也能直接require这个文件不需要额外挂全局变量。如果 vfs 文件很大JSON.stringify会把整个 base64 字符串放在一行这是正常的不要试图为它做格式化格式化反而会让 20MB 的文本文件产生额外的换行字符影响加载性能。有一点要特别留意这里的 key 是字体文件名例如MyFont-Regular.ttf。之后我们在pdfMake.fonts中定义字体映射时normal、bold等属性需要引用这些 key必须一字不差。文件名里最好不要有空格、括号和中文否则在拼接路径和映射表时容易出串行问题。我一般会把字体文件名统一改成小写加连字符例如myfont-regular.ttf。3.3 在Node.js中加载虚拟文件系统浏览器环境里pdfmake 可以直接把vfs_fonts.js作为 script 引入或者用打包工具把 vfs 对象import进来。但在 Node.js 服务端生成 PDF 时需要手动把 vfs 对象挂载到 pdfmake 实例上否则默认的 Roboto 会继续生效中文照样乱码。const pdfMake require(pdfmake/build/pdfmake); const myVfs require(./vfs_fonts.js); pdfMake.vfs myVfs; pdfMake.fonts { MyFont: { normal: MyFont-Regular.ttf, bold: MyFont-Bold.ttf, italics: MyFont-Regular.ttf, bolditalics: MyFont-Bold.ttf } }; const docDefinition { ... }; // 你的 PDF 文档定义 const pdfDoc pdfMake.createPdf(docDefinition); pdfDoc.getBuffer((buffer) { fs.writeFileSync(output.pdf, buffer); });这里的顺序很重要必须先给pdfMake.vfs赋值再设置pdfMake.fonts。原因在于设置fonts时pdfmake 内部会校验一下 vfs 中是否确实存在对应文件如果 vfs 还是默认的 Roboto 空壳你注册的字体名就会被忽略或者报错。而且在 Node.js 中require(./vfs_fonts.js)拿到的对象是我们在生成脚本中写入的那个导出对象一定要确认里面有vfs属性还是直接就是字体映射对象。如果生成脚本里module.exports vfsFonts那么myVfs就是{ MyFont-Regular.ttf: base64, ... }直接赋给pdfMake.vfs正好。如果生成脚本里导出的是{ vfs: { ... } }那就需要pdfMake.vfs myVfs.vfs多一层嵌套。这里是最容易踩坑的地方两套结构经常搞混。4. 写一个导出中文PDF的完整案例从表格到长文本4.1 定义文档结构文本、表格、页眉页脚字体问题解决之后实际生成 PDF 的过程仍然有几个细节值得注意。我们以一个典型中文报表为例标题、带中文表头的表格、页脚页码。下面是一段可以执行的完整 Node.js 代码假设 vfs 和 fonts 已经按照上一章配置好了。const pdfMake require(pdfmake/build/pdfmake); const fs require(fs); const myVfs require(./vfs_fonts.js); pdfMake.vfs myVfs; pdfMake.fonts { MyFont: { normal: MyFont-Regular.ttf, bold: MyFont-Bold.ttf, italics: MyFont-Regular.ttf, bolditalics: MyFont-Bold.ttf } }; const docDefinition { content: [ { text: 2025年度项目支出明细表, style: header }, { text: 制表时间2025-03-20, style: subheader }, { table: { widths: [auto, *, *, auto], body: [ [序号, 项目名称, 预算科目, 金额], [1, 服务器采购, 设备购置费, ¥ 20,000], [2, 软件授权, 技术服务费, ¥ 15,000] ] }, layout: lightHorizontalLines }, { text: 说明以上数据仅供内部参考最终以财务系统为准。, style: note } ], styles: { header: { fontSize: 18, bold: true, alignment: center, margin: [0, 10, 0, 10] }, subheader: { fontSize: 10, color: #666666, alignment: center, margin: [0, 0, 0, 20] }, note: { fontSize: 9, color: #999999, margin: [0, 20, 0, 0] } }, defaultStyle: { font: MyFont, fontSize: 10 }, footer: function(currentPage, pageCount) { return { text: currentPage.toString() / pageCount, alignment: center, fontSize: 9, color: #888888 }; } }; const pdfDoc pdfMake.createPdf(docDefinition); pdfDoc.getBuffer(buffer { fs.writeFileSync(report.pdf, buffer); console.log(PDF 已生成大小 (buffer.byteLength / 1024).toFixed(1) KB); });代码里widths数组定义表格列宽auto表示按内容自适应*表示按剩余空间平均分配。表格 body 是一个二维数组第一行是表头后面的行是数据。layout: lightHorizontalLines让表格只有水平线比较适合中文财务报表的观感。footer函数接收当前页数和总页数返回一个文本节点pdfmake 会在每一页重复渲染这段内容。defaultStyle.font设置为本篇注册的MyFont其余所有文本节点没有单独指定font都会继承这个默认值。styles 里的header、subheader、note都是可复用的命名样式在 content 节点中通过style字段引用。这里需要注意style 名称如果是自定义的必须与styles对象中的 key 完全一致pdfmake 不会做任何大小写归一化。4.2 分页控制与中文换行避坑中文和英文一个很大的不同是中文没有空格分词每个汉字都是独立的字符。pdfmake 在换行时默认按字符边界处理中文长文本换行通常没问题但遇到 URL、数字、英文单词混排时会出现整单词被拆开或者溢出列宽的情况。针对表格单元格尤其是包含长中文项目名称的单元格需要控制fontSize和列宽避免文字被挤成一行超高。pdfmake 对单元格内多行文本有两种处理方式一是手动在字符串里插入\n二是把文本节点拆分成数组每个数组元素独占一行。// 单元格内强制换行的常见写法 body: [ [序号, 项目名称, 预算科目, 金额], [1, { text: [服务器采购方案\n含维保] }, 设备购置费, ¥ 20,000] ]这里{ text: [...] }里的数组可以继续传字符串或带样式的小节点。pdfmake 会把它当成多段文本逐行渲染。如果你希望文本自动换行就把列宽设成*并且不要给单元格里的文本节点设置noWrap: true。noWrap是一个容易误用的选项一旦设了noWrap: true长中文会被强行延伸到表格外面。分页控制方面pdfmake 支持pageBreakBefore和pageBreakAfter但更常用的做法是在段落节点里加pageBreak: before。比如一个大表格前面需要强制开启新页可以在表格前置节点上设置{ text: 附表项目明细, pageBreak: before, style: subheader }这样无论前面的内容占多少空间该小节都会从新页开始。注意这个属性是放在具体节点上的不是放在styles里。放在styles里虽然不会报错但不生效。4.3 在浏览器和Node.js两种环境下的输出差异pdfmake 本身可以同时在浏览器和 Node.js 环境下运行但二者的输出细节有些差异。在浏览器里createPdf返回的对象可以直接调用.download()触发浏览器下载或者调用.open()在新窗口打开预览。在 Node.js 里没有 DOM 环境通常使用getBuffer()拿到 Buffer再写入文件或交给 HTTP 响应。之所以要单独提这个差异是因为浏览器环境下如果用import方式引入 pdfmake 的 ESM 模块vfs 的挂载方式可能和 CommonJS 不同。比如某些打包配置下import * as pdfMake from pdfmake/build/pdfmake得到的pdfMake.default才是真正的构造函数而pdfMake.vfs是 undefined导致你赋值的pdfMake.vfs根本没挂到实际实例上。这种问题在编译期不报错运行期不报错只有生成的 PDF 还是方框。排查方式也固定在赋值后打印一下pdfMake.vfs[MyFont-Regular.ttf]是否存在如果打印出来是 undefined说明挂错了对象。// 检查 vfs 是否挂载成功 pdfMake.vfs myVfs; console.log(vfs 字体文件数, Object.keys(pdfMake.vfs).length); if (!pdfMake.vfs[MyFont-Regular.ttf]) { console.error(字体文件没有注册成功请检查 vfs 的 key 是否匹配); }这个检查建议加在生成 PDF 之前省得生成 20 次后才在下载下来的文件里发现乱码。5. 中文PDF导出常见问题排查乱码、字体丢失、体积膨胀5.1 现象导出后中文变成“口口口”现象用 pdfmake 生成的 PDF 在浏览器预览或打开后所有中文都显示为一个个空心方框英文和数字正常。原因这是最典型的字体未注册问题。你的文档定义里可能写了font: SimSun但 pdfmake 的 vfs 中并没有这个字体文件的 base64 数据所以它拿 Roboto 渲染中文Roboto 没有中文字形于是画出方框。还有一种可能是 vfs 挂载成功但字体映射表pdfMake.fonts里的 key 和你写的font名不一致例如注册了MyFont却写了font: myfont。解决确认三处完全一致vfs_fonts.js中字体的 key 名如MyFont-Regular.ttf、pdfMake.fonts映射表中normal属性的引用值、文档定义中defaultStyle.font或节点上的font字段名。然后用上文 4.3 的打印方法检查 vfs 是否真正有对应的 key。如果排查后仍然乱码换一个最简单的方式只设置defaultStyle.font删掉节点级别的font覆盖排除优先级干扰。5.2 现象自定义字体没生效样式里的font变成默认现象样式里明明指定了font: MyChineseFont但生成 PDF 中文字体样式完全看不出来字体粗细、斜体都不对或者标题字体和正文字体没区别。原因pdfMake.fonts中字体映射表的 key 不存在pdfmake 在解析文档时会把无法识别的字体名静默替换为默认字体并且不会抛异常。另一个原因是只有normal注册了字体文件bold没有注册所以bold: true的标题实际使用普通字重渲染视觉上粗细一致给人“字体没生效”的感觉。解决检查pdfMake.fonts的配置确保bold、italics都有对应的 TTF 文件。如果想偷懒可以让bold指向同一个 regular 文件但这样加粗效果不会体现只能靠字号和颜色区分层级。真正想要粗体必须提供一个粗体字重文件。字体文件在转 base64 之前最好在本地双击确认这个 TTF 确实包含粗体字形很多免费字体只有一个字重。5.3 现象转换脚本报错或生成的vfs文件过大现象运行build-vfs.js时提示ENOENT找不到文件或者生成的vfs_fonts.js有 30MB加载后页面卡死。原因ENOENT通常是字体目录路径不对脚本里的fontsDir使用了相对路径而运行脚本时的工作目录不在项目根目录。vfs 文件过大的原因是直接加载了未裁剪的全量中文字体某些完整字库的 TTF 有 15MB 以上base64 编码后约 20MB浏览器端完全无法接受。解决脚本路径用path.join(__dirname, fonts)和项目所在位置无关。体积问题优先用pyftsubset做子集化只保留业务需要的字符。如果实在不想做子集也可以服务端生成 PDFvfs 文件放在服务器内存中由 Node.js 直接加载避免浏览器下载 20MB。服务端方案还有一个优点字体文件不需要通过 HTTP 提供给客户端减少了泄露字体文件本身的风险。5.4 现象同一份文档在浏览器正常、服务端乱码现象浏览器里打开的是正常的 PDF中文清晰但同样的 code 部署到 Node.js 服务端通过接口下载的 PDF 中文全变方框。原因浏览器环境里你可能通过打包工具把vfs_fonts.js作为静态资源import进来框架会自动把 vfs 挂载到 pdfmake 实例上而服务端代码里没有执行pdfMake.vfs myVfs或者服务端用的是另一个 pdfmake 实例vfs 没挂上去。另一个常见原因是服务端代码的require(./vfs_fonts.js)路径错了找到了项目里另一个默认 vfs 文件。解决把 vfs 挂载逻辑单独抽成一个模块浏览器和服务端共用。在服务端入口处打印一行日志记录Object.keys(pdfMake.vfs).length确认服务端加载的字体数量和本地一致。同时确保vfs_fonts.js以 CommonJS 形式导出require后直接就是对象不需要再取.vfs属性。我的习惯是在服务端每次重启后用curl拉一次测试接口从生成的 PDF 中提取文本检查是否包含中文实际字符而不是只看文件大小。6. 验证与进阶用pdftotext做回归测试把字体选择做成配置项6.1 验证生成结果是“真中文”而不是图形描边很多人在浏览器里肉眼看到 PDF 是中文就以为成功了但那个 PDF 里的中文可能是字体被渲染成轮廓曲线outline也就是把每个汉字画成矢量图形而不是真正的文本字符。这种情况在文本复制、搜索、OCR 时都会失败。要验证 PDF 中到底是不是可复制的文本可以用命令行工具提取文本内容。以常见的pdftotext为例pdftotext report.pdf report.txt grep -q 服务器采购 report.txt echo 中文文本正常 || echo PDF 中没有可提取的中文pdftotext会把 PDF 内嵌的文本数据提取出来。如果grep能找到预期中文说明 pdfmake 用了真正的字体字形映射文字可以选中、搜索、复制。如果提取出的文本是空白或者乱码即使视觉上正常也要考虑是不是用错了字体。这个验证方法建议写进 CI 流程每次改动文档模板后跑一遍避免回归。需要说明的是pdfmake 渲染的文本默认就是可复制的除非有人主动在字体层面做了一堆不规范的 post 表。所以这个测试更多是防呆确保环境切换时没挂错 vfs。6.2 把字体路径抽成配置文件方便换用不同字体项目里字体选择往往不是一成不变的。内部系统可能用轻量黑体对外客户账单可能要求宋体。把字体配置硬编码在生成逻辑里每次换字体都要改代码不划算。我一般在项目里维护一个fontConfig.js集中管理字体名称、vfs 引用和映射表。// fontConfig.js 示例 const defaultFonts { fontName: MyFont, vfs: require(./vfs_fonts.js), family: { normal: MyFont-Regular.ttf, bold: MyFont-Bold.ttf, italics: MyFont-Regular.ttf, bolditalics: MyFont-Bold.ttf } }; function applyFont(pdfMake, config) { pdfMake.vfs config.vfs; pdfMake.fonts {}; pdfMake.fonts[config.fontName] config.family; } module.exports { defaultFonts, applyFont };使用这个配置的方式是const { defaultFonts, applyFont } require(./fontConfig.js); applyFont(pdfMake, defaultFonts);这样一来后续如果想换用某开源字体只需要新建一个字体生成脚本把新的 TTF 转成vfs_fonts.js再在fontConfig.js里换掉vfs那一行引用即可。文档定义里的defaultStyle.font不用动只要保证新字体的fontName保持一致。这个技巧让我省了很多事。之前某个项目需要给不同客户输出不同风格的 PDF换了三种字体每次都是改动生成脚本里的字体目录然后重新跑一遍build-vfs.js再手动更新fontConfig.js。后来我把字体生成脚本也参数化了输入一个字体目录输出一份vfs_fonts.js和一份对应的fontConfig.js片段基本杜绝了“忘了改 mapping”之类的低级错误。从那以后我每次接手新的中文 PDF 需求都会强制走一遍完整的字体链路子集化、转 base64、挂 vfs、验证pdftotext全部脚本化。这些步骤看着多但每次都能提前暴露问题而不是等到交付时才在对方的电脑上翻车。希望帮到你。本文还有配套的精品资源点击获取