在Next.js应用路由中使用react-pdf渲染PDF文档的最佳实践

react-pdf是一个强大的React库，用于在浏览器和Node.js环境中生成PDF文档。本文将详细介绍如何在Next.js的应用路由(App Router)架构中正确使用react-pdf，特别是解决常见的环境相关错误。

理解react-pdf的环境问题

react-pdf提供了两种不同的构建版本：一个用于浏览器环境，一个用于Node.js环境。当我们在Next.js中使用时，可能会遇到"PDFViewer is a web specific API"这样的错误，这是因为Next.js的服务器端渲染(SSR)特性导致的。

解决方案一：动态导入与SSR禁用

对于需要在浏览器中显示PDF查看器的场景，最佳实践是使用Next.js的动态导入功能并禁用SSR：

import dynamic from 'next/dynamic';

const PDFViewer = dynamic(
  () => import('@react-pdf/renderer').then((mod) => mod.PDFViewer),
  { ssr: false }
);

这种方法确保PDFViewer组件只在客户端渲染，避免了服务器端不兼容的问题。同时，你还可以添加加载状态来提升用户体验。

解决方案二：服务器端PDF生成

如果你需要在服务器端生成PDF并提供下载，可以采用不同的方法：

1. 首先确保在next.config.js中添加配置：

experimental: {
  serverComponentsExternalPackages: ["@react-pdf/renderer"],
}

2. 创建一个API路由处理PDF生成：

import { renderToStream } from '@react-pdf/renderer';

export async function GET() {
  const stream = await renderToStream(<MyDocument />);
  return new Response(stream, {
    headers: {
      'Content-Type': 'application/pdf',
      'Content-Disposition': 'attachment; filename="document.pdf"',
    },
  });
}

样式与字体处理

在PDF文档中使用自定义字体时，需要注意：

1. 字体文件需要正确加载
2. 在StyleSheet中注册字体
3. 考虑字体文件的大小对性能的影响

const styles = StyleSheet.create({
  page: {
    fontFamily: 'CustomFont',
    padding: 10,
    fontSize: 14,
  },
});

性能优化建议

1. 对于复杂的PDF文档，考虑分块渲染
2. 使用React.memo优化文档组件
3. 在服务器端生成时，添加适当的缓存头
4. 考虑使用Web Worker处理大型PDF生成

总结

在Next.js应用路由中使用react-pdf需要特别注意环境差异问题。通过动态导入和SSR禁用可以解决浏览器端的渲染问题，而服务器端生成则需要不同的配置和方法。根据你的具体需求选择合适的实现方式，并注意性能优化和用户体验的平衡。