React-PDF 加载PDF文件时一直显示"Loading PDF..."的解决方案

在使用React-PDF库时，开发者可能会遇到PDF文件无法正常加载，界面一直显示"Loading PDF..."的问题。本文将深入分析这一常见问题的原因，并提供完整的解决方案。

问题现象

当开发者尝试使用React-PDF组件加载PDF文件时，界面始终停留在"Loading PDF..."状态，无法正常显示PDF内容。这种情况通常发生在以下几种场景：

1. 使用base64编码的PDF数据作为文件源
2. 在WebView环境中运行（如Android WebView）
3. 自定义配置了PDF.js工作线程

根本原因分析

经过技术排查，这个问题主要源于PDF.js工作线程(worker)的版本不匹配。具体表现为：

1. 工作线程加载失败：开发者尝试通过workerPort或workerSrc属性手动配置工作线程，但使用了不兼容的版本
2. 模块语法冲突：当使用ES模块(.mjs)格式的工作线程文件时，可能会遇到"Unexpected token 'export'"语法错误
3. API版本不一致：PDF.js主库和工作线程库的版本不一致导致通信失败

解决方案

1. 使用自动工作线程加载

React-PDF库内置了自动加载工作线程的功能，大多数情况下不需要手动配置。最简单的解决方案是：

import { Document, Page, pdfjs } from 'react-pdf';

// 不需要手动配置worker
function MyPDFViewer() {
  return (
    <Document file="example.pdf">
      <Page pageNumber={1} />
    </Document>
  );
}

2. 正确配置工作线程（如需自定义）

如果确实需要自定义工作线程路径，请确保：

1. 使用与React-PDF兼容的PDF.js版本
2. 使用CommonJS格式(.js)的工作线程文件，而非ES模块(.mjs)

正确配置方式：

import { pdfjs } from 'react-pdf';

// 使用正确版本的worker文件
pdfjs.GlobalWorkerOptions.workerSrc = '/path/to/pdf.worker.min.js';

3. 版本一致性检查

确保项目中安装的react-pdf、pdfjs-dist等依赖版本相互兼容。可以通过以下命令检查：

npm list react-pdf pdfjs-dist

最佳实践建议

1. 优先使用自动加载：除非有特殊需求，否则让React-PDF自动处理工作线程加载
2. 统一依赖版本：保持所有PDF相关依赖版本一致
3. 错误处理：为Document组件添加onLoadError回调以捕获加载错误
4. WebView特殊处理：在移动端WebView中，确保正确设置了文件访问权限

总结

React-PDF加载卡在"Loading PDF..."状态的问题通常源于工作线程配置不当。通过理解PDF.js的工作机制和遵循正确的配置方法，开发者可以轻松解决这一问题。记住，在大多数情况下，最简单的解决方案往往就是最好的解决方案 - 让React-PDF自动处理工作线程的加载和管理。