使用react-pdf查看PDF的部署阶段问题排查求助

常见原因及对应解决办法 #

1. PDF文件路径错误 #

开发环境中相对路径可能正常，但打包后项目结构变化，导致路径失效。

• 把PDF文件放在项目的public目录下（CRA/Vite通用），引用时使用绝对路径：

  // CRA项目
  <Document file={`${process.env.PUBLIC_URL}/your-file.pdf`} />
  // Vite项目
  <Document file={`/your-file.pdf`} />
  

• 检查打包后的dist（或build）目录，确认PDF文件是否存在，路径是否和代码中的引用一致。

2. 静态资源打包配置缺失 #

部分构建工具默认不会打包PDF这类非标准静态资源，导致部署后文件丢失。

• Vite项目：在vite.config.js中添加资源类型配置：

  export default defineConfig({
    assetsInclude: ['**/*.pdf']
  })
  

• CRA项目：无需额外配置，放在public目录的文件会直接复制到构建目录。

3. 服务器配置问题 #

服务器未正确处理静态资源请求，导致PDF文件无法被访问。

• Nginx配置示例（确保指向正确的构建目录，且支持前端路由）：

  server {
    listen 80;
    root /usr/share/nginx/html; # 指向dist目录路径
    index index.html;
  
    location / {
      try_files $uri $uri/ /index.html;
    }
  
    # 确保PDF的MIME类型被正确识别
    types {
      application/pdf pdf;
    }
  }
  

• 检查服务器返回状态码：浏览器控制台中查看PDF请求的状态，404表示路径错误，403表示权限不足，500表示服务器内部错误。

4. React-PDF Worker加载失败 #

生产环境下，react-pdf的Worker路径可能因打包而错乱，导致无法加载PDF解析器。

• 手动指定Worker路径（使用public目录中的worker文件）：

  import { Document, Page, Worker } from '@react-pdf/renderer';
  
  export default function PdfViewer() {
    return (
      <Worker workerUrl={`${process.env.PUBLIC_URL}/pdf.worker.min.js`}>
        <Document file={`${process.env.PUBLIC_URL}/your-file.pdf`}>
          <Page pageNumber={1} />
        </Document>
      </Worker>
    );
  }
  

• 或通过pdfjs-dist配置Worker：

  import pdfjs from 'pdfjs-dist';
  import pdfjsWorker from 'pdfjs-dist/build/pdf.worker.entry';
  
  pdfjs.GlobalWorkerOptions.workerSrc = pdfjsWorker;
  

5. 缓存或跨域问题 #

• 清除浏览器缓存，或强制刷新页面（Ctrl+F5），避免旧的错误路径被缓存。
• 如果使用CDN部署，确认PDF文件已上传至CDN，且路径配置正确，没有跨域限制。

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