Next.js集成react-pdf/renderer生产构建无限卡住问题求助

问题根源 #

本地开发正常但next build卡住，是因为@react-pdf/renderer依赖浏览器环境API（如Canvas），而Next.js默认的服务端渲染（SSR）会在构建时尝试处理这些客户端专属依赖，导致进程挂起。

解决方案 #

1. 动态导入PDF组件并禁用SSR #

将PDF相关组件改为客户端侧加载，避免SSR时触发依赖处理：

// 导入Next.js动态加载工具
import dynamic from 'next/dynamic';

// 动态加载PDFDownloadLink，禁用SSR
const PDFDownloadLink = dynamic(
  () => import('@react-pdf/renderer').then(mod => mod.PDFDownloadLink),
  { ssr: false, loading: () => <div>加载中...</div> }
);

// 同样动态加载PDFGenerator组件
const PDFGenerator = dynamic(
  () => import('../components/PDFGenerator'), // 替换为你的组件实际路径
  { ssr: false }
);

// 原使用代码保持不变
export default function YourPage() {
  return (
    <PDFDownloadLink
      document={<PDFGenerator />}
      fileName="recipe.pdf"
      className="button-background w-full text-center text-color py-2 px-4 rounded mt-10"
    >
      {({ loading }) => loading ? 'Loading document...' : 'Download PDF'}
    </PDFDownloadLink>
  );
}

2. 配置Next.js打包规则 #

修改next.config.js，添加依赖转译和服务端外部化配置：

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 转译react-pdf及其依赖，确保打包工具正确处理
  transpilePackages: ['@react-pdf/renderer', 'pdf-lib'],
  webpack: (config, { isServer }) => {
    // 服务端构建时排除客户端专属依赖
    if (isServer) {
      config.externals.push({
        'canvas': 'commonjs canvas',
        'pdf-lib': 'commonjs pdf-lib'
      });
    }
    return config;
  }
};

module.exports = nextConfig;

3. 针对App Router的额外处理 #

如果使用Next.js App Router，需要在使用PDF组件的文件顶部添加'use client'指令，明确标记为客户端组件：

'use client';

import dynamic from 'next/dynamic';

// 后续动态导入和组件使用代码...

4. 更新react-pdf版本 #

运行命令更新到最新稳定版，修复已知兼容性问题：

npm update @react-pdf/renderer
# 或使用yarn
yarn upgrade @react-pdf/renderer

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