react-pdf渲染时导致应用卡顿冻结的原因及解决办法

问题原因 #

1. 无限重渲染循环：直接在usePDF的document参数中传入<MyDocument/>，每次组件渲染都会生成新的React元素引用，触发usePDF钩子反复重新生成PDF实例，进而导致组件无限重渲染，最终页面卡死。Codesandbox的环境因渲染优化或版本差异未触发该问题。
2. 版本兼容性bug：本地项目的@react-pdf/renderer版本与Codesandbox中使用的版本不一致，部分旧版本存在usePDF钩子的内存泄漏或渲染循环问题。

可行解决方案 #

方案1：传递组件而非实例化元素给usePDF #

将document参数改为传递组件本身，避免每次渲染创建新元素引用：

const ContractorCardView = () => {
  // 直接传入组件MyDocument，而非<MyDocument/>
  const [instance] = usePDF({ document: MyDocument });
  
  return <div>
    <button onClick={() => window.open(instance.url)}>打开PDF</button>
  </div>;
};

如果需要给MyDocument传递props，使用usePDF的props参数：

const [instance] = usePDF({
  document: MyDocument,
  props: { title: "自定义标题" } // 这里传递组件所需的props
});

方案2：用useMemo缓存PDF配置 #

若必须传递实例化元素，通过useMemo缓存配置对象，确保仅在依赖变化时重新创建：

import { useMemo } from 'react';

// ...

const ContractorCardView = () => {
  // 空依赖数组确保仅组件挂载时创建一次配置
  const pdfConfig = useMemo(() => ({
    document: <MyDocument />
  }), []);

  const [instance] = usePDF(pdfConfig);
  
  return <div>
    <button onClick={() => window.open(instance.url)}>打开PDF</button>
  </div>;
};

方案3：对齐react-pdf版本 #

查看Codesandbox项目中@react-pdf/renderer的版本，将本地项目的版本修改为一致，消除版本差异带来的bug：

1. 在本地项目的package.json中修改版本号：

"@react-pdf/renderer": "x.x.x" // 替换为Codesandbox中的具体版本

2. 重新安装依赖：

npm install
# 或使用yarn
yarn install

额外排查建议 #

• 确认本地项目的React版本在16.8及以上（@react-pdf/renderer依赖React Hooks）。
• 打开浏览器控制台查看是否有隐性报错，部分错误会间接导致页面无响应。

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