Gatsby项目中使用react-pdf导入PDF时出现文件加载失败报错

报错Failed to load PDF file的核心原因有两个：一是Gatsby的静态资产解析规则没有匹配PDF文件格式，导致文件路径解析错误；二是react-pdf依赖的PDF.js Worker没有做Gatsby环境适配，PDF.js会把所有解析阶段的异常统一抛出为该报错，哪怕PDF文件路径正确，也会因为加载链路断裂触发错误。

具体落地修复步骤 #

1. 调整PDF静态文件的托管方式，避免路径解析错误 #

• 优先选择Gatsby原生支持的静态目录托管PDF：把mypdf.pdf从src/images移动到项目根目录的static/文件夹下（完整路径为项目根目录/static/mypdf.pdf）。这种方式Gatsby会在构建时直接把PDF映射到站点根路径，不需要走webpack打包流程，不会因为打包哈希、路径重写规则导致文件404。
• 对应调整组件代码，去掉原来的PDF import语句，直接给<Document>组件传站点根路径：

  // 删除原来的 import mypdf from "../images/mypdf.pdf";
  // 直接指定文件路径
  <Document file="/mypdf.pdf" onLoadSuccess={onDocumentLoadSuccess} className="container">
  

• 如果需要继续用src目录下的import方式引入PDF，需要在gatsby-node.js中添加webpack规则，明确让file-loader处理pdf后缀文件：

  // gatsby-node.js 中新增配置
  exports.onCreateWebpackConfig = ({ actions }) => {
    actions.setWebpackConfig({
      module: {
        rules: [
          {
            test: /\.pdf$/,
            use: [
              {
                loader: 'file-loader',
                options: {
                  name: `static/[name].[hash].[ext]`,
                },
              },
            ],
          },
        ],
      },
    })
  }
  

2. 本地适配PDF.js Worker，避免外部资源加载失败 #

react-pdf 底层依赖PDF.js解析PDF内容，默认会从外部CDN拉取worker脚本，Gatsby本地环境下如果存在网络拦截、路径重写规则，会导致worker加载失败，连带PDF文件报错。

• 在引用react-pdf的组件文件顶部新增worker配置，直接从本地node_modules引入worker资源，不依赖外部网络：

  import { pdfjs } from 'react-pdf';
  // 用webpack的url导入模式获取本地worker的可访问路径
  import workerUrl from 'pdfjs-dist/build/pdf.worker.min.js?url';
  // 全局指定worker路径
  pdfjs.GlobalWorkerOptions.workerSrc = workerUrl;
  

3. 修正组件逻辑细节，避免渲染异常 #

• 调整分页按钮的禁用逻辑，解决numPages未加载完成时的判断异常：

  <button 
    type="button" 
    disabled={!numPages || pageNumber >= numPages} 
    onClick={nextPage}
  >
    Next
  </button>
  

• 给<Page>组件新增renderTextLayer={false}配置，避免生产构建时文本层加载报错导致的渲染中断：

  <Page pageNumber={pageNumber} renderTextLayer={false} />
  

验证方法 #

启动项目开发服务后，打开浏览器开发者工具的网络面板，检查两个核心资源的加载状态：

• PDF本体文件的请求返回200状态码
• pdf.worker.min.js脚本的请求返回200状态码
  两个资源加载正常后，组件就会正确识别PDF总页数、渲染页面内容，不会再抛出加载失败的报错。

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