React PDF快速切换文件时messageHandler为null报错求助

问题描述 #

使用react-pdf时，快速切换PDF文件会触发错误：作为Worker通信通道的messageHandler为null。尝试过多种方案仍未解决，需定位根本原因并找到可行解决方案。

根因推测 #

• Worker未完成初始化：PDF.js Worker可能在初始化未完成时就被调用
• Worker初始化被中断：快速导航等操作可能打断初始化流程
• 多次初始化损坏状态：即使将Worker初始化移至根布局，多次尝试仍可能破坏Worker状态
• React严格模式重渲染：Strict Mode引发的重渲染会导致首次加载成功，但第二次渲染调用getPage时触发错误
• 快速切换PDF：用户切换PDF时，Worker未正确初始化、切换时Worker未配置到位或页码为null，结合Strict Mode的重渲染，第二次渲染发送PDF文件出错，最终触发getPage报错

错误详情 #

PDF.js Worker未正确初始化或状态损坏，导致messageHandler为null，触发如下错误：

// 来自PDF.js源码：
Transport.getPage = function getPage({
  /* ... */
}) {
  return this.messageHandler.sendWithPromise("GetPage", { /* ... */ });
  //       ^^^^^^^^^^^^^^ 这里就是错误中为null的部分
};

运行时错误栈：

Unhandled Runtime Error
TypeError: Cannot read properties of null (reading "sendWithPromise')
Call Stack
Worker Transport.getPage
node_modules\pnpm\pdfjs-dist@3.11.174\node_modules\pdfjs-dist\build\pdf.js (2398:0)
PDFDocumentProxy.getPage
node_modules\pnpm\pdfjs-dist@3.11.174\node_modules\pdfjs-dist\build\pdf.js (1225:0)
loadPage
node_modules\pnpm\react-pdf@7.7.3_@types+react@18.2.21_react-dom@18.2.0_react@18.2.0_react@18.2.0\node_modules\react-pdf\dist\esm\Page.js (120:43)
commitHookEffectListMount
node_modules\pnpm\next@13.4.19_react-dom@18.2.0_react@18.2.0_react@18.2.0_sass@1.82.0\node_modules\next\dist\compiled\react-dom\cjs\react-dom.development.js (19980:0)
commitPassiveMountEffects
node_modules\pnpm\next@13.4.19_react-dom@18.2.0_react@18.2.0_react@18.2.0_sass@1.82.0\node_modules\next\dist\compiled\react-dom\cjs\react-dom.development.js (22035:0)
commitPassiveMountOnFiber
node_modules\pnpm\next@13.4.19_react-dom@18.2.0_react@18.2.0_react@18.2.0_sass@1.82.0\node_modules\next\dist\compiled\react-dom\cjs\react-dom.development.js (22141:0)
recursivelyTraversePassiveMountEffects
node_modules\pnpm\next@13.4.19_react-dom@18.2.0_react@18.2.0_react@18.2.0_sass@1.82.0\node_modules\next\dist\compiled\react-dom\cjs\react-dom.development.js (22119:0)
commitPassiveMountOnFiber
node_modules\pnpm\next@13.4.19_react-dom@18.2.0_react@18.2.0_react@18.2.0_sass@1.82.0\node_modules\next\dist\compiled\react-dom\cjs\react-dom.development.js (22138:0)
recursivelyTraversePassiveMountEffects
node_modules\pnpm\next@13.4.19_react-dom@18.2.0_react@18.2.0_react@18.2.0_sass@1.82.0\node_modules\next\dist\compiled\react-dom\cjs\react-dom.development.js (22119:0)

已尝试的解决方案 #

1. 将PDF Worker初始化移至根布局：避免多次初始化，配置全局Worker路径

// 基于最新react-pdf版本
pdfjs.GlobalWorkerOptions.workerSrc = `//unpkg.com/pdfjs-dist@${pdfjs.version}/build/pdf.worker.min.mjs`;

2. 文件切换时重置numPages状态：切换PDF时重置页码状态

React.useEffect(() => {
  setNumPages(undefined);
}, [file]);

3. 为

   return (<Document />)
   

   组件添加唯一Key：强制组件重新渲染

<Document 
  key={file.name} 
  file={file} 
  onLoadSuccess={onDocumentLoadSuccess}
/> 

4. 条件渲染Page组件：仅在文档加载完成后渲染页面

const [isDocumentReady, setIsDocumentReady] = useState(false);

function onDocumentLoadSuccess({ numPages }) {
  setNumPages(numPages);
  setIsDocumentReady(true);
}

return (
  <Document
    file={file}
    onLoadSuccess={onDocumentLoadSuccess}
    options={{
      cMapUrl: 'cmaps/',
      cMapPacked: true,
    }}
  >
    {isDocumentReady &&
      Array.from(new Array(numPages), (el, index) => (
        <Page key={`page_${index + 1}`} pageNumber={index + 1} />
      ))}
  </Document>
);

5. 更新react-pdf版本：从7.7.3升级到9.2.1，但因与pdfjs版本不兼容引入新问题

6. 测试不同PDF Worker格式：尝试.js和.mjs格式的Worker

// 使用.js格式Worker
pdfjs.GlobalWorkerOptions.workerSrc = `//unpkg.com/pdfjs-dist@${pdfjs.version}/build/pdf.worker.min.js`;

// 使用.mjs格式Worker
pdfjs.GlobalWorkerOptions.workerSrc = `//unpkg.com/pdfjs-dist@${pdfjs.version}/build/pdf.worker.min.mjs`;

7. 自定义Hook初始化Worker：尝试通过Hook确保Worker仅初始化一次，但因版本问题失败

import { useEffect, useState } from "react";
import * as pdfjs from "pdfjs-dist";
import pdfjsWorker from "pdfjs-dist/build/pdf.worker.mjs";

declare global {
  interface Window {
    pdfjsWorkerInitialized?: boolean;
  }
}

export default function usePDFWorker() {
  const [workerReady, setWorkerReady] = useState(false);

  useEffect(() => {
    if (typeof window === "undefined") return; // 跳过SSR

    const initializeWorker = () => {
      try {
        pdfjs.GlobalWorkerOptions.workerSrc = pdfjsWorker;
        setWorkerReady(true);
      } catch (error) {
        console.error("PDF worker初始化失败:", error);
      }
    };

    if (!window.pdfjsWorkerInitialized) {
      window.pdfjsWorkerInitialized = true;
      initializeWorker();
    }
  }, []);

  return workerReady;
}

8. 文件切换时重置numPages为0：在加载成功时重置页码为0或实际值

function onDocumentLoadSuccess({ numPages }) {
  setNumPages(numPages ?? 0);
}

9. 移除冗余Worker初始化：删除多个文件中的重复初始化代码，仅在根布局初始化一次

10. 处理React严格模式重渲染：尝试避免Strict Mode下第二次渲染时重新初始化Worker

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