Vue本地PDF预览时中文乱码如何解决？

Question

在使用 Vue 实现本地 PDF 预览时，常借助 `pdf.js` 库解析和渲染 PDF 文件。然而，部分包含中文的 PDF 在预览时会出现乱码或方框字符，主要原因在于 PDF 嵌入的中文字体未被正确加载或浏览器不支持该字体。尤其是在本地开发环境下，跨域限制或字体资源路径错误会加剧此问题。此外，若原始 PDF 使用了非标准编码或未嵌入子集字体，`pdf.js` 无法正常解析字形，导致中文显示异常。如何配置 `pdf.js` 支持中文字体并确保字体资源正确加载，成为解决该问题的关键技术难点。

Answer 1

一、问题背景与技术挑战概述

在现代前端开发中，Vue 框架因其轻量、响应式和组件化设计而被广泛应用于文档预览类功能的构建。结合 pdf.js 实现本地 PDF 预览已成为常见方案。然而，当处理包含中文内容的 PDF 文件时，开发者常遇到“乱码”或“方框字符（□）”等显示异常问题。

根本原因在于：PDF 文件中嵌入的中文字体未被正确解析或渲染环境不支持该字体。尤其在本地开发环境下，由于跨域策略限制、静态资源路径配置不当，或原始 PDF 使用了非标准编码、未完整嵌入字体子集，导致 pdf.js 无法获取有效的字形映射，最终出现文本渲染失败。

二、从浅层到深层的技术分析路径

1. 现象识别：预览界面出现方框、空白或乱码字符，英文正常但中文异常。
2. 初步排查：检查是否为编码问题，确认 PDF 是否使用 CID 字体（如 Adobe-GB1）并嵌入了中文字库。
3. 运行时日志分析：通过浏览器控制台查看 pdf.js 抛出的警告信息，例如：Warning: Error during font loading 或 Cannot find font file。
4. 网络请求监控：使用 DevTools 查看字体文件（.ttf/.woff）是否因 404 或 CORS 被阻断。
5. 深入机制理解：pdf.js 默认使用自定义字体回退机制，在缺少对应字体时尝试加载内置或远程字体资源。

三、核心解决方案：配置 pdf.js 支持中文字体

要解决中文显示问题，关键在于显式配置字体回退路径，并确保这些字体资源可被安全访问。

步骤	操作说明	涉及文件/配置项
1	准备常用中文字体文件（如 simsun.ttf、simhei.ttf）	public/fonts/
2	设置 CMapReaderFactory 和 StandardFontDataFactory	pdfjsLib.GlobalWorkerOptions
3	指定 CMap 和字体数据的基础路径	workerSrc, cMapUrl, cMapPacked
4	启用 CORS 兼容服务或代理字体请求	vue.config.js devServer.proxy

四、具体实现代码示例

import * as pdfjsLib from 'pdfjs-dist';
import pdfWorker from 'pdfjs-dist/build/pdf.worker.min.js';

// 设置 worker 路径
pdfjsLib.GlobalWorkerOptions.workerSrc = new URL(
  'pdfjs-dist/build/pdf.worker.min.js',
  import.meta.url
).toString();

// 配置中文字体支持
const CMAP_URL = '/cmaps/';
const STANDARD_FONT_DATA_URL = '/standard_fonts/';

const loadingTask = pdfjsLib.getDocument({
  url: 'sample-chinese.pdf',
  cMapUrl: CMAP_URL,
  cMapPacked: true,
  standardFontDataUrl: STANDARD_FONT_DATA_URL
});

将以下目录结构部署至 public/ 目录下以确保资源可访问：

• public/cmaps/
• public/standard_fonts/
• public/fonts/simsun.ttf

五、跨域与构建工具适配策略

在 Vue CLI 或 Vite 构建环境中，需特别注意静态资源的引用方式。以下是 Vite 环境下的代理配置示例：

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '/cmaps': {
        target: 'http://localhost:3000',
        rewrite: (path) => path.replace(/^\/cmaps/, '/public/cmaps')
      }
    }
  }
})

六、Mermaid 流程图：中文 PDF 渲染故障诊断流程

graph TD A[PDF预览出现方框] --> B{是否仅中文异常?} B -- 是 --> C[检查PDF字体嵌入情况] B -- 否 --> D[排查整体解析错误] C --> E[查看DevTools字体请求] E --> F{字体请求404或CORS?} F -- 是 --> G[配置public路径或代理] F -- 否 --> H[确认CMAP与StandardFontData路径] H --> I[替换为已知兼容字体测试] I --> J[问题解决]

七、高级优化建议与生产实践

• 对 PDF 进行预处理：使用 Ghostscript 嵌入子集化中文字体，减小体积并提升兼容性。
• 构建字体服务中间层：统一管理 TTF/WOFF 字体资源，提供带缓存头的 HTTP 接口供 pdf.js 动态加载。
• 采用 Web Worker 分离解析任务，避免主线程阻塞，提升大文件加载体验。
• 利用 PDFJS.disableFontFace = true 强制使用 canvas 绘制文本，规避部分浏览器字体沙箱限制。
• 集成字体检测模块，在页面加载前动态注入 @font-face 规则。
• 监控用户上报的 PDF 解析异常，建立常见字体缺失白名单机制。
• 使用 pdf-lib 或 hummus 在服务端重写 PDF 字体引用，作为兜底方案。
• 考虑引入 OCR 技术应对完全无文本层的老版扫描件。