Word与Pdfmake中文本编码兼容性问题

Question

在使用 Pdfmake 生成 PDF 文档时，若直接导入 Word 文档中的文本内容，常出现中文乱码或字符丢失问题。其根源在于 Word 文件（.docx）默认采用 UTF-8 编码并嵌入字体信息，而 Pdfmake 若未正确配置字体和编码格式（如未引入支持中文的自定义字体如微软雅黑或思源黑体），则无法解析 UTF-8 中文字符，导致渲染失败。此外，Word 中的特殊格式字符（如全角空格、换行符）在转换过程中可能被误处理，进一步加剧兼容性问题。解决该问题需确保 Pdfmake 的字体仓库中包含完整中文字体文件，并显式设置文档字体与编码，同时对原始文本进行规范化预处理。

Answer 1

使用 Pdfmake 生成 PDF 时处理 Word 文档中文乱码的深度解析与解决方案

1. 问题现象：从 Word 导入文本后出现中文乱码或字符丢失

在现代企业文档自动化系统中，常需将 Word（.docx）文档内容导入并转换为 PDF 格式。然而，开发者普遍反馈：当使用 Pdfmake 进行渲染时，中文字符显示为方框、问号甚至完全缺失。

• 典型表现：中文显示为“□□”或“”
• 原因初判：字体未加载、编码不匹配、特殊字符未转义
• 影响范围：跨平台部署、国际化项目、多语言文档生成

2. 技术根源分析：编码与字体机制的错位

Pdfmake 基于 JavaScript 构建，其底层依赖于 TTF 字体文件 和明确的编码声明。而 .docx 文件本质是 ZIP 容器，内部 XML 使用 UTF-8 编码存储文本，并通过 Office 应用程序动态绑定系统字体（如微软雅黑）进行渲染。

对比维度	Word (.docx)	Pdfmake
文本编码	UTF-8（默认）	依赖运行环境，需显式设置
字体管理	嵌入或引用系统字体	必须手动注册 TTF/OTF 文件
换行符处理	<w:br>, 全角空格等富格式	仅识别 \n 或
中文支持	自动适配	需引入完整中文字体子集

3. 深层机制剖析：Pdfmake 的字体注册模型

Pdfmake 不自带中文字体，所有字体必须通过 pdfMake.fonts 显式注册。若未提供包含 CJK（中日韩）字符集的字体文件，则无法绘制这些字形。

pdfMake.fonts = {
    SimSun: {
        normal: 'SimSun.ttf',
        bold: 'SimSun-Bold.ttf',
        italics: 'SimSun-Italic.ttf',
        bolditalics: 'SimSun-BoldItalic.ttf'
    },
    SourceHanSansCN: {
        normal: 'SourceHanSansCN-Regular.otf',
        bold: 'SourceHanSansCN-Bold.otf'
    }
};
    

4. 特殊字符兼容性挑战：从 Word 提取文本的陷阱

使用 docxtemplater 或 mammoth.js 解析 .docx 时，以下字符易引发问题：

1. 全角空格（U+3000）被误作普通空格
2. 软回车（Shift+Enter）生成 <w:cr/> 节点，需转为 \n
3. 制表符、分页符未标准化
4. 上下标、合并字符导致 Unicode 解码异常

5. 解决方案框架：三步构建鲁棒的中文 PDF 生成链路

为确保高保真还原 Word 内容，应建立如下流程：

graph TD A[读取.docx文件] --> B{解析为JSON} B --> C[文本规范化预处理] C --> D[替换全角/特殊字符] D --> E[注入自定义中文字体] E --> F[配置Pdfmake文档字体] F --> G[生成PDF并输出]

6. 实践示例：完整代码实现

以下是结合 mammoth.js 与 pdfmake 的生产级示例：

const mammoth = require("mammoth");
const fs = require("fs");

async function convertDocxToPdf(docxPath, outputPath) {
    const arrayBuffer = fs.readFileSync(docxPath).buffer;
    const result = await mammoth.extractRawText({ arrayBuffer });
    let text = result.value;

    // 规范化处理
    text = text
        .replace(/\u3000/g, " ")           // 全角空格 → 半角
        .replace(/\r\n|\r|\n/g, "\n")       // 统一换行符
        .trim();

    // 配置字体
    pdfMake.fonts = {
        STHeiti: {
            normal: 'STHeiti.ttf',          // 黑体，支持简体中文
            bold: 'STHeiti-Bold.ttf'
        }
    };

    const docDefinition = {
        content: [text],
        defaultStyle: {
            font: 'STHeiti'
        }
    };

    const pdfDoc = pdfMake.createPdf(docDefinition);
    pdfDoc.write(outputPath);
}
    

7. 高级优化策略：字体子集化与性能平衡

完整中文字体文件通常超过 5MB，可采用以下方式优化：

• 使用 fontmin 工具提取实际用到的字符子集
• 服务端缓存已处理字体资源
• 前端异步加载字体，避免阻塞主线程
• 对高频文档模板预生成字体映射表

8. 跨平台部署注意事项

在 Docker 容器或 Serverless 环境中，需特别注意：

环境	字体路径配置	推荐做法
Node.js (本地)	相对路径 ./fonts/	使用 path.resolve()
Docker	/usr/share/fonts/	COPY 字体到镜像
AWS Lambda	/tmp/	解压字体至临时目录
浏览器端	Blob URL	Base64 编码内联

9. 监控与调试手段

可通过以下方法定位乱码问题：

1. 启用 Pdfmake 的 debug 模式查看字体加载日志
2. 打印文本的 charCodeAt() 验证是否为有效 UTF-16
3. 使用 Chrome DevTools 查看生成的 PDF 字体嵌入情况
4. 对比原始 .docx 与输出 PDF 的字符覆盖率
5. 添加测试用例验证常见生僻字（如“镕”、“煊”）
6. 集成 CI/CD 中的视觉回归测试

10. 行业最佳实践总结

大型企业文档系统已普遍采用如下架构模式：

graph LR Client --上传.docx--> APIGateway APIGateway --> Lambda[解析服务] Lambda --> FontCache[(字体缓存)] Lambda --> TextNorm[文本归一化引擎] TextNorm --> PdfGen[Pdfmake 渲染] PdfGen --> S3[存储PDF] S3 --> Client