vue-pdf加载中文乱码如何解决？

Question

在使用 vue-pdf 组件加载包含中文的 PDF 文件时，部分用户会遇到中文显示为乱码或方框的问题。该问题通常源于 PDF 文件未嵌入中文字体，或浏览器默认字体不支持中文渲染。由于 vue-pdf 基于 Mozilla 的 PDF.js 实现，其文本绘制依赖于字体嵌入与解析能力。当原始 PDF 使用了系统未识别的中文字体且未完整嵌入时，PDF.js 无法正确绘制字符，导致乱码。此外，构建过程中若未正确处理静态资源路径，也可能影响字体加载。因此，如何确保 PDF 文件内嵌中文字体或通过自定义字体补全机制解决渲染异常，成为使用 vue-pdf 时亟需解决的关键问题。

Answer 1

解决 vue-pdf 组件中中文显示乱码或方框问题的深度剖析与实践方案

1. 问题现象与初步定位

在使用 vue-pdf 组件渲染包含中文内容的 PDF 文件时，部分用户反馈出现文字显示为“方框”或“乱码”的现象。该问题并非普遍存在于所有 PDF 文件，通常出现在由特定办公软件（如 WPS、旧版 Word）导出且未嵌入中文字体的文档中。

• 表现形式：中文字符无法正常绘制，替代为矩形符号（□）或乱码字符
• 影响范围：跨浏览器复现（Chrome、Firefox 均可能出现）
• 依赖技术栈：vue-pdf → PDF.js（Mozilla 开源项目）

2. 根本原因分析

深入探究其底层机制，可将问题归因于以下三类：

1. 字体未嵌入：原始 PDF 在生成过程中未将所用中文字体（如宋体、黑体、微软雅黑）完整嵌入文件
2. 字体子集化：部分工具仅嵌入实际使用的字符子集，缺失生僻字导致回退失败
3. PDF.js 字体回退机制缺陷：当字体缺失时，PDF.js 默认不自动映射到系统支持的中文字体

3. 技术原理图解

下图为 PDF 渲染流程中字体处理的关键路径：

graph TD
    A[PDF 文件加载] --> B{是否嵌入字体?}
    B -- 是 --> C[解析 TTF/OTF 字体数据]
    B -- 否 --> D[尝试使用系统字体]
    D --> E{浏览器是否支持?}
    E -- 支持 --> F[正常渲染]
    E -- 不支持 --> G[显示方框/乱码]
    C --> H[创建 Canvas 文本层]
    H --> I[调用 WebGL 或 2D Context 绘制]
    

4. 常见排查手段与验证方法

检查项	工具/方法	预期结果
字体嵌入状态	Adobe Acrobat Pro → “文件→属性→字体”	列出所有字体及其“已嵌入”状态
PDF.js 日志输出	启用 PDFJS.verbosity = 1	控制台输出字体加载警告
网络请求监控	Chrome DevTools → Network Tab	查看是否有字体资源请求失败
本地打开效果	双击 PDF 用系统阅读器打开	若本地正常，则问题出在前端渲染

5. 解决方案一：确保 PDF 内嵌中文字体

最根本的解决方案是从源头控制 PDF 生成质量。推荐在服务端或客户端生成 PDF 时强制嵌入字体：

• 使用 Puppeteer 生成 PDF 时，CSS 中指定本地字体并确保路径正确
• 使用 jsPDF + html2canvas 时，预先加载 WebFont 并应用至 DOM
• 通过 pdf-lib 修改已有 PDF，注入缺失字体（需许可证允许）

6. 解决方案二：自定义 PDF.js 字体补全机制

对于无法修改源文件的场景，可通过扩展 PDF.js 的字体映射逻辑实现动态替换：

// 在 Vue 组件 mounted 阶段注入自定义字体
import pdfjsLib from 'pdfjs-dist'
import CMapReaderFactory from 'pdfjs-dist/lib/display/cmap'

// 设置中文字体映射
pdfjsLib.GlobalWorkerOptions.workerSrc = '/static/pdf.worker.min.js'

const customFontMap = {
  'SimSun': 'SourceHanSansSC-Regular.otf',
  'FangSong': 'SourceHanSerifSC-Regular.otf',
  'Microsoft-YaHei': 'MicrosoftYaHei.ttf'
}

// 拦截字体加载钩子（需 patch PDF.js 内部逻辑）
pdfjsLib.getDocument({
  url: 'example.pdf',
  cMapUrl: '/cmaps/',
  cMapPacked: true,
  fontExtraProperties: true,
  disableFontFace: false // 关键：允许创建 @font-face
}).promise.then(pdf => {
  console.log('PDF loaded with potential font fixes applied.')
})

    

7. 构建配置注意事项

在 Vue CLI 或 Vite 项目中，静态资源路径处理不当会导致字体文件 404：

• 确认 /public/static/ 目录存在且包含 pdf.worker.min.js 和 cmaps/
• Webpack 配置中添加 file-loader 处理 .otf/.ttf 文件
• Vite 用户需使用 publicDir 正确暴露资源

8. 替代方案评估

若长期受困于 PDF.js 的字体限制，可考虑如下替代路径：

方案	优点	缺点
后端转图片预览	兼容性极佳，规避字体问题	SEO 差，大文件性能差
PDF.js + Service Worker 缓存字体	离线可用，提升加载速度	实现复杂，PWA 兼容性要求高
集成 Mozilla 官方 viewer.html	功能完整，更新及时	难以定制 UI，体积较大

9. 高级优化策略

针对企业级应用场景，建议实施以下工程化措施：

1. 建立 PDF 质量检测流水线，自动识别非嵌入字体文档
2. 部署字体代理服务，统一提供合规中文字体资源
3. 利用 WebAssembly 加速字体解析过程
4. 结合 Intersection Observer 实现懒加载多页文档
5. 对用户上传文件进行预处理（Ghostscript 重生成）
6. 记录字体加载失败日志，用于后续分析改进
7. 采用 CSS @supports 检测环境渲染能力并降级展示
8. 使用 canvas.textBaseline 调整垂直对齐避免裁剪
9. 监控 FP（First Paint）与 FCP（First Contentful Paint）指标
10. 实现字体 fallback chain，优先尝试本地缓存字体

10. 社区与生态支持现状

目前 vue-pdf 社区活跃度一般，核心依赖 PDF.js 更新频繁但中文支持仍属边缘需求。GitHub 上多个 issue 反映类似问题（#12789, #13045），Mozilla 团队建议通过 CMap 和 Font Substitution 机制自行扩展。阿里云、腾讯文档等大型平台已构建私有化 PDF 渲染引擎，集成 Noto Sans CJK 等开源字体以保障一致性体验。