React-PDF部署至测试环境后自定义字体加载失败求助

问题情况 #

使用react-pdf的<PDFDownloadLink>生成PDF，本地Express服务运行正常，但部署到测试环境后，新添加的自定义字体无法加载。已将字体放在/src/fonts/MyFont.woff，并在font-face.css中配置，但测试环境开发者工具Source标签显示字体未加载。此前同路径的另一款自定义字体可正常工作。

相关代码与文件结构 #

MyComponent.jsx

<PDFDownloadLink
    document={<MyPDF />}
    fileName="summary.pdf"
>
    {({ blob, url, loading, error }) => {
        console.log({blob, url, loading, error});
        return !!loading ? 'Creating PDF' : 'Download PDF'
    }}
</PDFDownloadLink>

MyPDF.jsx

import MyFont from '../fonts/MyFont.woff';

const MyPDF = (props) => {

    Font.register({ 
        family: 'MyFont', 
        src: MyFont, 
        fontStyle: 'normal', 
        fontWeight: 'normal'
    });

    // PDF内容逻辑
};

font-face.css

@font-face {
    font-family: MyFont;
    src: url('../fonts/MyFont.woff); /* 注意此处缺少闭合引号 */
}

文件结构

src/
├── css/
│   ├── font-face.css
├── components/
│   ├── MyComponent.jsx
│   └── MyPDF.jsx
└── fonts/
    ├── MyFont.woff

排查与解决步骤 #

1. 修复CSS语法错误 #

font-face.css中url的路径缺少闭合引号，这会导致CSS解析失败，是最直接的问题：

@font-face {
    font-family: MyFont;
    src: url('../fonts/MyFont.woff'); /* 添加缺失的引号 */
}

2. 确认字体文件的打包输出路径 #

测试环境中，构建工具（如Webpack/Vite）会对静态资源进行处理，需确认：

• 检查测试环境的dist（或对应输出目录）下，fonts/MyFont.woff是否存在，路径是否与正常加载的字体一致。
• 若使用Webpack，检查资源加载配置，确保woff文件被正确输出到指定目录：

  module.exports = {
    module: {
      rules: [
        {
          test: /\.(woff|woff2|eot|ttf|otf)$/i,
          type: 'asset/resource',
          generator: {
            filename: 'fonts/[name][ext]' // 确保输出到fonts目录
          }
        }
      ]
    }
  };
  

3. 调整Font.register的资源引用方式 #

如果打包后字体文件名被添加哈希（如MyFont.abc123.woff），直接导入的路径可能无法被react-pdf正确识别，可尝试：

• 将字体文件移至项目根目录的public/fonts下（Create React App等框架的静态资源目录），然后修改Font.register：

  Font.register({ 
      family: 'MyFont', 
      src: '/fonts/MyFont.woff', // 使用绝对路径
      fontStyle: 'normal', 
      fontWeight: 'normal'
  });
  

• 同时更新font-face.css的路径为绝对路径：

  @font-face {
      font-family: MyFont;
      src: url('/fonts/MyFont.woff');
  }
  

4. 验证字体文件完整性 #

新字体文件可能存在损坏或格式兼容问题：

• 替换MyFont.woff为之前可正常加载的字体文件，测试是否能在测试环境加载，排除文件本身的问题。
• 检查字体文件的格式是否为标准woff格式，可通过在线工具验证。

5. 查看控制台错误信息 #

在测试环境打开浏览器控制台，查看是否有字体加载相关的404错误或资源解析错误，根据错误信息定位具体路径问题。

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