React集成react-pdf路由跳转后偶现Failed to load PDF file报错

问题现象 #

• 基于create-react-app搭建的React项目，引入react-pdf实现PDF预览功能
• 首次进入PDF预览页面时，PDF可100%正常渲染
• 站内路由跳转到其他页面后，再导航返回PDF预览页，有概率多次触发「Failed to load PDF file」报错，导致PDF加载失败
• 报错效果如下：
  
• 正常加载效果如下：
  

问题根因 #

• 原有代码使用react-pdf/dist/esm/entry.webpack的引入方式，会在组件每次挂载时重复初始化PDF.js worker，路由切换组件卸载时旧worker未被正确销毁，新旧worker实例抢占解析资源导致文件加载失败
• 组件卸载时没有中断正在进行的PDF加载请求，返回页面时重复发起请求出现竞态冲突
• 代码中定义的imageKitURL开头存在多余空格，拼接后的PDF路径存在非法前缀，部分缓存场景下会触发请求异常

修复步骤 #

1. 修正基础配置 #

首先删除imageKitURL开头的多余空格，修正路径格式：

// 修正前：const imageKitURL = ' https://ik.imagekit.io/kwmvfjr0r';
const imageKitURL = 'https://ik.imagekit.io/kwmvfjr0r';

替换react-pdf引入方式，手动全局配置worker路径，避免重复初始化：

1. 执行npm install pdfjs-dist安装和react-pdf版本匹配的pdfjs依赖
2. 从node_modules/pdfjs-dist/build目录下找到pdf.worker.min.js文件，复制到项目public目录下
3. 从node_modules/pdfjs-dist目录下找到cmaps文件夹，整体复制到项目public目录下，解决中文PDF显示异常问题
4. 修改依赖引入代码：

import { Document, Page, pdfjs } from 'react-pdf';
import { useState, useEffect, useRef } from 'react';
import 'react-pdf/dist/esm/Page/AnnotationLayer.css';
// 全局仅初始化一次worker，引用本地静态资源
pdfjs.GlobalWorkerOptions.workerSrc = '/pdf.worker.min.js';

2. 增加卸载清理逻辑，解决竞态问题 #

通过useRef记录正在进行的PDF加载任务，组件卸载时主动销毁未完成的任务，同时给Document组件增加唯一key，强制路由返回时重新挂载组件，避免复用旧实例导致的状态异常。
完整修复后的组件代码：

function ReactPDF() {
    const imageKitURL = 'https://ik.imagekit.io/kwmvfjr0r';
    const pdf = `${imageKitURL}/test_files/file-example_PDF_1MB.pdf`;
    // 记录加载中的任务实例
    const loadingTaskRef = useRef(null);

    const [numPages, setNumPages] = useState(null);
    const [pageNumber, setPageNumber] = useState(1);

    // 组件卸载时销毁未完成的加载任务
    useEffect(() => {
        return () => {
            if (loadingTaskRef.current) {
                loadingTaskRef.current.destroy();
                loadingTaskRef.current = null;
            }
        }
    }, [])

    function onDocumentLoadSuccess({ numPages }) {
        setNumPages(numPages);
        setPageNumber(1);
    }

    function onDocumentLoadError(err) {
        console.error('PDF加载异常：', err);
    }

    function changePage(offset) {
        setPageNumber((prevPageNumber) => prevPageNumber + offset);
    }

    function previousPage() {
        changePage(-1);
    }

    function nextPage() {
        changePage(1);
    }

    return (
        <>
            <div>
                <p>
                    Page {pageNumber || (numPages ? 1 : '--')} of {numPages || '--'}
                </p>
                <button type="button" disabled={pageNumber <= 1} onClick={previousPage}>
                    Previous
                </button>
                <button type="button" disabled={pageNumber >= numPages} onClick={nextPage}>
                    Next
                </button>
            </div>
            <Document 
                key={pdf}
                file={pdf} 
                onLoadSuccess={onDocumentLoadSuccess}
                onLoadError={onDocumentLoadError}
                options={{
                    cMapUrl: '/cmaps/',
                    cMapPacked: true
                }}
            >
                <Page pageNumber={pageNumber} />
            </Document>
        </>
    );
}

3. 可选优化项 #

• 对PDF预览组件使用React.lazy做懒加载，路由离开时自动卸载组件实例，减少内存占用
• 跨域加载PDF时，确认资源服务配置了正确的CORS响应头，避免偶发跨域拦截
• 可增加1-2次自动重试逻辑，应对网络波动导致的偶发加载失败

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