如何解决@react-pdf/renderer使用自定义字体报Unknown font format错误

Unknown font format报错本质不是字体路径错误，是@react-pdf/renderer在前端运行环境下无法直接解析相对路径指向的本地字体文件，可按以下步骤调整：

1. 调整字体引入方式 #

不要直接在Font.register的src字段填写相对路径，先把字体文件作为模块导入到当前代码文件：

// 代码顶部引入字体文件，路径对应你本地字体文件位置
import NunitoRegular from "./ttf/Nunito-Regular.ttf";

常规React/Vite项目默认支持ttf格式静态资源解析，无需额外修改构建配置。

2. 调整字体注册逻辑 #

不要把Font.register放在组件内部，避免组件重复渲染时重复执行注册逻辑，把注册逻辑移到组件外部，传入导入的字体变量：

import { StyleSheet, Document, Page, Text, Font } from '@react-pdf/renderer';
import NunitoRegular from "./ttf/Nunito-Regular.ttf";

// 组件外完成字体注册
Font.register({
  family: "Nunito",
  src: NunitoRegular,
});

const styles = StyleSheet.create({
  page: {
    alignItems: "center",
  },
  text: {
    fontFamily: "Nunito",
  },
});

const MainPage = () => {
  return (
    <Document>
      <Page size="A4" style={styles.page}>
        <Text style={styles.text}>Reserve Number: </Text>
      </Page>
    </Document>
  );
};

可选排查方向 #

• 确认当前使用的Nunito-Regular.ttf文件本身没有损坏，可替换官方源下载的字体文件重试
• 如果你是在Node.js服务端环境使用@react-pdf/renderer，可直接传入绝对路径加载字体：

import path from 'path';

Font.register({
  family: "Nunito",
  src: path.resolve(__dirname, './ttf/Nunito-Regular.ttf'),
});

• 升级@react-pdf/renderer到最新正式版，部分旧版本存在字体解析的已知兼容问题

内容的提问来源于stack exchange，提问作者Hamid