在Next.js项目中配置@react-pdf/renderer自定义字体遇阻

安全阿岳

2026-7-28

Next.js 中 @react-pdf/renderer 自定义字体问题解决

你遇到的核心问题是字体路径错误，Next.js 对静态资源的访问规则和普通 React 项目不同，具体修正方案如下：

1. 修正字体路径

Next.js 的 public 目录是静态资源根目录，访问时不需要加上 public/ 前缀。把字体路径里的 public/ 去掉，直接从根目录开始写：

// pdf.ts 修正后的代码
import { Document, Page, Text, Image, Link, View, StyleSheet, PDFViewer, Font} from '@react-pdf/renderer';

Font.register({
  family: 'PrimaSerif',
  fonts: [
    {
      src: '/assets/font/PrimaSerif/FontPrimaSerif_Regular.ttf',
      fontStyle: 'normal', 
      fontWeight: 'normal',
    },
    {
      src: '/assets/font/PrimaSerif/FontPrimaSerif_Bold.ttf',
      fontStyle: 'normal', 
      fontWeight: 'bold',
    }
  ],
});

2. 验证文件路径准确性

确认字体文件确实存在于 public/assets/font/PrimaSerif/ 目录下
注意文件名大小写（部署到 Linux 服务器时大小写敏感，本地开发可能忽略）

3. 处理服务器组件兼容性

如果你的 PDF 组件是服务器组件，@react-pdf/renderer 的字体注册逻辑在服务端无法正确加载本地字体，需要：

将 PDF 相关代码放在客户端组件中（在组件文件顶部加 'use client' 指令）
或者用 next/dynamic 禁用 SSR 导入组件：

// 页面组件示例
import dynamic from 'next/dynamic';

// 禁用 SSR 加载 PDF 组件
const PDFViewerComponent = dynamic(() => import('../components/pdf'), {
  ssr: false,
});

export default function PDFPage() {
  return <PDFViewerComponent />;
}