React-PDF 在 Next.js 15 中的 ESM 导入问题解决方案

问题背景

在使用 Next.js 15 构建应用时，开发者可能会遇到与 React-PDF 相关的模块导入错误。具体表现为控制台报错"Module not found: ESM packages (@react-pdf/renderer) need to be imported"，这是由于 Next.js 15 对 ESM 模块的严格校验机制导致的。

问题分析

React-PDF 是一个用于在 React 应用中生成 PDF 文档的流行库。在 Next.js 15 环境中，当开发者尝试通过动态导入方式使用 React-PDF 组件时，系统会抛出 ESM 模块导入错误。这是因为：

1. Next.js 15 加强了对 ESM 模块的校验
2. React-PDF 采用了 ESM 模块规范
3. 传统的 CommonJS 导入方式不再被推荐

解决方案

方法一：配置 Next.js 放宽 ESM 校验

在 next.config.js 文件中添加以下配置：

const nextConfig = {
  experimental: {
    esmExternals: 'loose',
  },
}

这种方法简单直接，但属于临时解决方案，可能会在未来版本的 Next.js 中被移除。

方法二：创建中间组件文件

更规范的解决方案是创建一个中间组件文件：

1. 首先创建 pdfViewer.tsx 文件：

import { PDFViewer } from "@react-pdf/renderer";
export default PDFViewer;

2. 然后在需要使用的地方动态导入：

const PDFViewer = dynamic(() => import("./pdfViewer"), {
  ssr: false,
});

这种方法遵循了 Next.js 的最佳实践，通过中间文件解决了 ESM 模块的动态导入问题。

方法三：完整 Next.js 配置方案

对于更复杂的 React-PDF 使用场景，可以配置完整的 next.config.js：

const nextConfig = {
  webpack: (config) => {
    config.resolve.alias.canvas = false;
    config.resolve.alias.encoding = false;
    return config;
  },
  transpilePackages: ["@react-pdf/renderer"],
};

这种配置方案：

1. 处理了 React-PDF 的 canvas 依赖
2. 解决了编码相关的问题
3. 明确指定了需要转译的包

最佳实践建议

1. 优先考虑方法二的中间组件方案，它最符合 Next.js 的设计理念
2. 对于简单项目，方法一的配置方案可以作为快速解决方案
3. 当项目需要更复杂的 PDF 生成功能时，采用方法三的完整配置
4. 注意 React-PDF 的版本兼容性，确保使用最新稳定版

技术原理

Next.js 15 对 ESM 模块的严格校验是为了：

• 提高应用性能
• 确保模块加载的一致性
• 为未来的 Web 标准做好准备

React-PDF 作为 ESM 模块，需要通过正确的方式导入才能充分发挥其性能优势。通过上述解决方案，开发者可以在享受 Next.js 15 新特性的同时，继续使用 React-PDF 的强大功能。