使用react-pdf@10.2.0时出现DOMMatrix is not defined错误求助

这个问题本质是DOMMatrix是浏览器专属API，而pdfjs-dist（react-pdf的依赖）在初始化时会尝试访问它——如果你的项目存在服务端渲染（SSR）逻辑，或者开发环境下的预构建/预执行触发了非浏览器环境的代码运行，就会抛出这个错误。很多开发者在使用react-pdf结合SSR框架（包括React Router的SSR项目）时都遇到过同类问题，下面是几种验证有效的解决方案：

方案1：添加DOMMatrix polyfill #

安装polyfill包并在项目入口引入，补全非浏览器环境下的API支持：

npm install dommatrix
# 或 yarn add dommatrix

在项目入口文件（比如main.tsx）顶部添加：

import 'dommatrix';

方案2：确保react-pdf仅在客户端渲染 #

如果你的项目启用了SSR，需要动态导入react-pdf组件，避免在服务端执行相关代码：

import { useEffect, useState } from 'react';

export default function Home() {
  const [PDFViewer, Document, Page] = useState([null, null, null]);

  useEffect(() => {
    import('react-pdf').then((module) => {
      setPDFViewer([module.PDFViewer, module.Document, module.Page]);
    });
  }, []);

  if (!PDFViewer[0]) return <div>加载中...</div>;

  return (
    <PDFViewer width="100%" height="800px">
      <Document file="/sample.pdf">
        <Page pageNumber={1} />
      </Document>
    </PDFViewer>
  );
}

方案3：指定pdfjs-dist的浏览器入口 #

如果是Vite或Webpack项目，通过别名配置强制使用pdfjs-dist的浏览器版本，避免加载node环境的代码：

Vite（vite.config.ts） #

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      'pdfjs-dist': 'pdfjs-dist/build/pdf',
    },
  },
});

Webpack #

在webpack.config.js的resolve.alias中添加同样的配置即可。

你可以先尝试方案1，大部分场景下添加polyfill就能解决问题；如果是SSR场景，方案2更稳妥。

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