7步精通pdfmake中文字体配置：从乱码到完美显示的实战指南

2026-04-07 12:46:01作者：廉皓灿Ida

现象解析：中文字体显示异常的四大典型表现

在使用pdfmake生成PDF文档时，中文字符无法正常显示是开发者最常遇到的问题。根据项目中examples/pdfs/目录下的各类示例文件对比分析，中文显示异常主要表现为以下四种情况：

空白占位：文档中所有中文字符位置显示为空白
** tofu 字符**：中文字符被替换为□或�等替代符号
部分显示：仅部分简单汉字可显示，复杂汉字丢失
布局错乱：中文字符导致行高、间距等布局参数异常

这些问题根源在于pdfmake默认集成的Roboto字体（位于fonts/Roboto/目录）是一套西文字体，其字符集中不包含任何中文字形信息。当系统尝试渲染中文内容时，由于找不到对应字形，只能使用默认替代符号或直接留白。

核心原理：pdfmake字体渲染机制深度剖析

要彻底解决中文字体问题，首先需要理解pdfmake的字体管理架构。项目核心字体处理逻辑集中在src/base.js和src/PDFDocument.js两个关键文件中，其工作流程可分为三个阶段：

字体加载机制

pdfmake采用虚拟文件系统（VFS）管理字体资源，所有字体文件必须通过base64编码后嵌入到PDF中。这一过程通过src/virtual-fs.js模块实现，确保字体资源能在浏览器和Node.js环境中一致工作。

字体注册流程

字体注册主要通过pdfmake.addFonts()方法完成，该方法定义在src/index.js中。每个字体需要提供normal、bold、italics和bolditalics四种字重的配置，即使某些字重实际使用同一文件。

文本渲染优先级

当渲染文本时，系统会按照以下优先级查找字体：

元素级font属性指定的字体
样式对象中定义的font属性
文档默认样式(defaultStyle)中的font设置
系统默认字体(Roboto)

这种层级结构允许开发者灵活控制不同内容的字体显示效果。

实施步骤：7步完美配置中文字体

1. 字体选型：选择适合业务场景的中文字体

根据项目需求和许可协议，推荐三类中文字体：

开源免费类：思源黑体、Noto Sans SC、Source Han Sans
系统预装类：微软雅黑(Windows)、苹方(Mac)、文泉驿( Linux)
商业授权类：方正系列、汉仪系列

⚠️ 注意：商业字体需确保已获得使用授权，避免法律风险

2. 字体文件准备与存放

将选择的字体文件（通常为.ttf或.otf格式）放置在项目中合理位置。建议参照现有fonts/Roboto/目录结构，创建fonts/Chinese/目录统一管理中文字体文件。

3. 创建字体配置文件

参照src/browser-extensions/fonts/Roboto.js的结构，创建中文字体配置文件：

// fonts/Chinese/SimHei.js
export default {
  vfs: {
    'SimHei.ttf': {
      data: 'base64编码的字体文件内容',
      encoding: 'base64'
    }
  },
  fonts: {
    SimHei: {
      normal: 'SimHei.ttf',
      bold: 'SimHei.ttf',  // 如果没有专门的粗体文件，可复用常规体
      italics: 'SimHei.ttf',
      bolditalics: 'SimHei.ttf'
    }
  }
};

4. 字体文件转base64编码

使用Node.js工具将字体文件转换为base64编码：

// scripts/encode-font.js
const fs = require('fs');
const path = require('path');

function encodeFontToBase64(fontPath) {
  const fontData = fs.readFileSync(fontPath);
  return fontData.toString('base64');
}

// 使用示例
const base64Data = encodeFontToBase64('fonts/Chinese/SimHei.ttf');
console.log(base64Data);

将输出的base64字符串替换到步骤3创建的配置文件中。

5. 注册字体到pdfmake

在应用入口文件中注册中文字体：

import pdfMake from 'pdfmake/build/pdfmake';
import ChineseFont from './fonts/Chinese/SimHei';

// 注册字体
pdfMake.addFonts(ChineseFont);

6. 文档中应用中文字体

在文档定义中指定中文字体：

const docDefinition = {
  content: [
    { text: '医院门诊收费单', font: 'SimHei', fontSize: 24, bold: true },
    // 其他内容...
  ],
  defaultStyle: {
    font: 'SimHei'  // 设置全局默认字体
  }
};

7. 验证与调试

生成PDF后，重点检查：

所有中文字符是否正常显示
字体粗细、斜体等样式是否正确
文档体积是否在可接受范围
不同设备和PDF阅读器兼容性

场景应用：医疗报告系统PDF生成实例

以医疗行业的检验报告生成为例，展示完整的中文字体应用方案。

业务需求分析

医疗检验报告需要包含：

患者基本信息（姓名、性别、年龄等）
检验项目列表及结果
参考范围和单位
医生签名和医院信息

完整实现代码

import pdfMake from 'pdfmake/build/pdfmake';
import fs from 'fs';
import path from 'path';
import ChineseFonts from './fonts/Chinese';

// 注册中文字体
pdfMake.addFonts(ChineseFonts);

// 读取医院logo
const logoData = fs.readFileSync('examples/images/sampleImage.jpg', 'base64');

// 检验报告数据
const reportData = {
  patientName: '张三',
  gender: '男',
  age: 45,
  testDate: '2023-10-15',
  reportDate: '2023-10-16',
  items: [
    { name: '白细胞计数', result: '6.5', unit: '10^9/L', reference: '4.0-10.0' },
    { name: '红细胞计数', result: '4.8', unit: '10^12/L', reference: '4.3-5.8' },
    { name: '血红蛋白', result: '145', unit: 'g/L', reference: '130-175' },
    // 更多检验项目...
  ],
  doctor: '李四',
  hospital: '示例医院'
};

// 构建文档定义
const docDefinition = {
  pageSize: 'A4',
  pageMargins: [40, 60, 40, 60],
  header: {
    columns: [
      { image: `data:image/jpeg;base64,${logoData}`, width: 60 },
      { 
        text: `${reportData.hospital} 检验报告`, 
        font: 'SimHei', 
        fontSize: 18, 
        bold: true,
        alignment: 'center'
      },
      { text: '报告编号: LAB20231016001', font: 'SimHei', alignment: 'right' }
    ]
  },
  content: [
    { text: '患者信息', font: 'SimHei', fontSize: 14, bold: true, margin: [0, 20, 0, 10] },
    {
      table: {
        widths: ['*', '*', '*', '*'],
        body: [
          ['姓名', reportData.patientName, '性别', reportData.gender],
          ['年龄', reportData.age, '检验日期', reportData.testDate]
        ]
      },
      font: 'SimHei'
    },
    { text: '检验结果', font: 'SimHei', fontSize: 14, bold: true, margin: [0, 20, 0, 10] },
    {
      table: {
        headerRows: 1,
        widths: ['*', 'auto', 'auto', '*'],
        body: [
          ['项目名称', '结果', '单位', '参考范围'],
          ...reportData.items.map(item => [
            item.name, item.result, item.unit, item.reference
          ])
        ]
      },
      style: 'tableStyle'
    },
    { 
      text: `检验医生: ${reportData.doctor}`, 
      font: 'SimHei', 
      alignment: 'right', 
      margin: [0, 30, 0, 0] 
    }
  ],
  styles: {
    tableStyle: {
      font: 'SimHei',
      margin: [0, 5, 0, 15]
    }
  },
  defaultStyle: {
    font: 'SimHei',
    fontSize: 12
  }
};

// 生成PDF
pdfMake.createPdf(docDefinition).download(`检验报告_${reportData.patientName}_${reportData.reportDate}.pdf`);

实现效果

图：使用pdfmake生成的医疗检验报告（示意图）

常见误区与解决方案

误区1：配置字体后仍显示乱码

根源：字体文件路径错误或base64编码不完整 解决方案：

使用绝对路径加载字体文件
验证base64编码完整性（可通过在线工具解码测试）
检查字体文件是否损坏（尝试用字体查看器打开）

误区2：设置默认字体后部分内容仍用Roboto

根源：样式优先级理解错误 解决方案：

检查是否有元素级font属性覆盖了默认设置
确认defaultStyle配置是否正确应用
检查src/StyleContextStack.js中的样式继承逻辑

误区3：PDF文件体积过大

根源：中文字体文件完整嵌入导致体积膨胀 解决方案：

使用fonttools工具创建字体子集：

pyftsubset SimHei.ttf --text-file=used-chars.txt --output-file=SimHei-subset.ttf

只包含文档中实际使用的字符集
对字体文件进行压缩优化

技术对比：pdfmake字体方案vs其他PDF库

特性	pdfmake	jsPDF	PDFKit
字体管理	VFS系统，base64嵌入	需手动添加字体	直接引用文件路径
中文支持	需自定义配置	需插件支持	需手动配置
易用性	中（声明式API）	低（命令式API）	中（过程式API）
体积优化	支持字体子集	有限支持	支持字体子集
浏览器兼容性	良好	良好	需Node.js环境

pdfmake在中文字体配置的便捷性和跨环境一致性方面表现突出，特别适合需要在浏览器和服务器端同时使用的场景。

优化策略：提升中文字体渲染性能

字体加载优化

按需加载：只在需要生成PDF时才加载字体资源
预编码处理：构建时预先生成base64编码的字体文件
字体缓存：在Node.js环境中缓存已加载的字体数据

文档结构优化

使用样式继承减少重复字体定义
合理组织内容结构，避免频繁字体切换
优化表格和列表的字体设置

高级优化技巧

实现字体fallback机制，应对字体缺失场景
使用字体变量技术减少字重文件数量
结合src/qrEnc.js等模块实现二维码与中文混排优化

未来趋势：PDF生成技术发展方向

字体技术演进

Variable Fonts：单文件支持多种字重和样式，减少文件体积
Web Fonts集成：直接使用网络字体资源，无需本地文件
动态字体子集：根据文档内容动态生成最小字体子集

pdfmake发展方向

从项目src/目录结构分析，未来可能增强：
- src/browser-extensions/中的字体自动加载机制
- src/helpers/中的字体处理工具函数
- src/Renderer.js中的文本布局优化

进阶学习资源

核心模块研究：
- 字体加载逻辑：src/base.js
- 文档渲染流程：src/Renderer.js
- 虚拟文件系统：src/virtual-fs.js
官方示例：
- 基础字体配置：examples/basics.js
- 样式应用：examples/styling_properties.js
扩展功能：
- 二维码生成：src/qrEnc.js
- SVG处理：src/SVGMeasure.js
- 表格布局：src/tableLayouts.js