安装react-pdf后遇canvas模块未找到错误，Gatsby网站PDF渲染求助

问题原因 #

react-pdf依赖的pdfjs-dist需要canvas原生模块，但Gatsby的服务端渲染（SSR）环境无法直接处理这类Node.js原生模块，导致构建时出现找不到模块的错误。

具体解决步骤 #

• 安装canvas及系统依赖
  先安装canvas包：

  npm install canvas --save
  # 或使用yarn
  yarn add canvas
  

  若使用Linux系统，需先安装系统层面的依赖库，否则canvas可能编译失败：

  sudo apt-get install libcairo2-dev libjpeg-dev libpango1.0-dev libgif-dev build-essential g++
  

• 配置Gatsby忽略canvas的SSR处理
  在项目根目录的gatsby-node.js文件中添加以下配置（无此文件则直接新建），让Gatsby在构建/开发的HTML阶段用null loader处理canvas模块，避免SSR报错：

  exports.onCreateWebpackConfig = ({ stage, loaders, actions }) => {
    if (stage === "build-html" || stage === "develop-html") {
      actions.setWebpackConfig({
        module: {
          rules: [
            {
              test: /canvas/,
              use: loaders.null(),
            },
          ],
        },
      });
    }
  };
  

• 优化react-pdf的导入方式
  通过动态导入或React.lazy延迟加载PDF组件，避免在SSR阶段加载相关模块：

  import React, { lazy, Suspense } from 'react';
  
  // 封装了react-pdf的组件
  const PDFViewer = lazy(() => import('./components/PDFViewer'));
  
  const MyPage = () => {
    return (
      <Suspense fallback={<div>加载PDF中...</div>}>
        <PDFViewer pdfUrl="/path/to/your/pdf.pdf" />
      </Suspense>
    );
  };
  
  export default MyPage;
  

  示例PDFViewer组件内容：

  import { Document, Page } from 'react-pdf';
  
  const PDFViewer = ({ pdfUrl }) => {
    return (
      <Document file={pdfUrl}>
        <Page pageNumber={1} />
      </Document>
    );
  };
  
  export default PDFViewer;
  

• 清理缓存重新构建
  执行以下命令清理Gatsby缓存并重新启动项目：

  gatsby clean
  npm run develop
  # 或构建生产环境
  npm run build
  

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