本文详解如何在 vite + npm 管理字体（如 @fontsource/source-sans-pro）的现代前端项目中，为 pdfmake 正确注入带哈希的 woff 字体 url，避免硬编码路径失效问题。
本文详解如何在 vite + npm 管理字体（如 @fontsource/source-sans-pro）的现代前端项目中，为 pdfmake 正确注入带哈希的 woff 字体 url，避免硬编码路径失效问题。
在基于 Vite 构建的前端项目中使用 pdfmake 时，一个常见痛点是：字体资源由构建工具自动哈希并重命名（如 source-sans-pro-latin-400-normal-69491b82.woff），无法预先写出稳定 URL。若直接在 pdfMake.fonts 中填入静态路径（如 "./fonts/SourceSans-Regular.woff"），生产环境将因 404 报错——这正是你遇到的核心问题。
幸运的是，Vite 提供了优雅的解决方案：利用 import.meta.url 动态解析模块上下文中的资源路径。它会在构建阶段被 Vite 自动重写为最终部署时的真实 URL（含哈希），且支持相对路径引用，完美适配字体文件。
✅ 正确做法：用 new URL(..., import.meta.url) 获取运行时字体 URL
首先，确保你的字体文件已通过 @fontsource 正确安装并可被 Vite 解析：
npm install @fontsource/source-sans-pro
然后，在你的 PDF 初始化逻辑文件（如 pdfUtils.js 或组件脚本）中，按字体变体分别导入并生成 URL：
import pdfMake from 'pdfmake/build/pdfmake';
// ✅ 动态导入字体文件（Vite 会自动处理哈希）
import normalWoff from '@fontsource/source-sans-pro/files/source-sans-pro-latin-400-normal.woff';
import boldWoff from '@fontsource/source-sans-pro/files/source-sans-pro-latin-700-normal.woff';
import italicWoff from '@fontsource/source-sans-pro/files/source-sans-pro-latin-400-italic.woff';
import boldItalicWoff from '@fontsource/source-sans-pro/files/source-sans-pro-latin-700-italic.woff';
// ✅ 使用 import.meta.url 安全生成浏览器可访问的绝对 URL
const normalUrl = new URL(normalWoff, import.meta.url).href;
const boldUrl = new URL(boldWoff, import.meta.url).href;
const italicUrl = new URL(italicWoff, import.meta.url).href;
const boldItalicUrl = new URL(boldItalicWoff, import.meta.url).href;
// 配置 pdfMake 字体映射（注意：pdfmake 仅支持 TTF/OTF，但实测最新版 v0.2.10+ 已兼容 WOFF/WOFF2）
pdfMake.fonts = {
SourceSans: {
normal: normalUrl,
bold: boldUrl,
italics: italicUrl,
bolditalics: boldItalicUrl
}
};
⚠️ 注意事项：
@fontsource/xxx/files/...导入方式依赖于@fontsource包提供的.woff文件导出（查看其package.json中"exports"字段确认）。若未暴露.woff，可改用public/fonts/目录 +import.meta.env.BASE_URL方式（见下文备选方案）。pdfmake官方文档推荐使用.ttf字体，但 v0.2.7 及更高版本（2024 年起）已原生支持 WOFF/WOFF2 解析，无需额外转换；若遇渲染异常，建议回退至.ttf格式（可用 transfonter.org 在线转换）。- 不要混用 CSS 引入（如
@import "@fontsource/..."）与pdfMake.fonts—— 前者仅作用于 DOM 渲染，对 pdfmake 生成的 PDF 无效。
? 备选方案：使用 public/ 目录 + BASE_URL（更稳定，推荐用于生产）
若 @fontsource 的文件导出不可靠，或需更强控制力，推荐将字体文件手动放入 public/fonts/：
public/
└── fonts/
├── source-sans-pro-regular.woff2
├── source-sans-pro-bold.woff2
├── source-sans-pro-italic.woff2
└── source-sans-pro-bold-italic.woff2
然后在 JS 中这样引用（完全规避构建路径问题）：
// ✅ 稳定可靠：public 下资源始终以 BASE_URL 为根
const BASE_URL = import.meta.env.BASE_URL || '/';
pdfMake.fonts = {
SourceSans: {
normal: `${BASE_URL}fonts/source-sans-pro-regular.woff2`,
bold: `${BASE_URL}fonts/source-sans-pro-bold.woff2`,
italics: `${BASE_URL}fonts/source-sans-pro-italic.woff2`,
bolditalics: `${BASE_URL}fonts/source-sans-pro-bold-italic.woff2`
}
};
? 验证是否生效
配置完成后，生成 PDF 时务必指定 defaultStyle.font：
const docDefinition = {
content: [{ text: '你好，世界！', fontSize: 16 }],
defaultStyle: { font: 'SourceSans' } // ← 关键：启用自定义字体
};
pdfMake.createPdf(docDefinition).download('中文PDF示例.pdf');
若 PDF 中中文/西文均清晰显示、无方块或乱码，即表示字体注入成功。
? 总结
| 方法 | 适用场景 | 优势 | 风险 |
|---|---|---|---|
new URL(..., import.meta.url) |
字体已通过 npm 包管理且导出 .woff
|
零配置、自动化哈希适配 | 依赖包导出完整性 |
public/fonts/ + BASE_URL |
追求最大稳定性或需自定义字体 | 路径绝对可控、调试直观 | 需手动维护字体文件 |
无论采用哪种方式，核心原则不变：让 pdfMake.fonts 中的 URL 指向浏览器可直接 fetch() 的有效资源地址。Vite 的 import.meta.url 机制正是为此类“构建时未知路径”场景而生的最佳实践。
