解决 PDFKit 在 Next.js 中缺失 Helvetica.afm 文件的问题

在使用 PDFKit 库与 Next.js 框架结合开发时，开发者可能会遇到一个常见问题：系统报错提示缺少 Helvetica.afm 字体文件。这个问题通常表现为在本地开发或生产环境中运行时，控制台会抛出文件不存在的错误。

问题本质分析

PDFKit 是一个流行的 Node.js PDF 生成库，它依赖于一些内置的字体度量文件（.afm）来正确渲染文本。其中 Helvetica.afm 是最基础的字体度量文件之一。在标准的 Node.js 环境中，PDFKit 会自动处理这些依赖文件的加载和访问。

然而，当 PDFKit 被集成到 Next.js 应用中时，特别是当使用 Next.js 的服务端组件或 API 路由功能时，由于 Next.js 的特殊构建和打包机制，这些字体文件可能不会被正确地包含在最终的构建产物中。这导致了运行时文件缺失的错误。

解决方案演进

早期临时解决方案

最初，开发者可能会采用手动创建缺失文件和目录的方法：

1. 在 .next/server/vendor-chunks 目录下创建 data 子目录
2. 手动将 Helvetica.afm 文件放置在该目录中

这种方法虽然能暂时解决问题，但明显不够优雅，且每次重新构建后都需要重复操作，不适合生产环境使用。

Next.js 配置解决方案

随着对问题理解的深入，社区发现了更根本的解决方案：通过 Next.js 的配置明确指定 PDFKit 作为服务端外部包。这种方法利用了 Next.js 提供的配置选项，确保 PDFKit 及其依赖能够被正确处理。

对于 Next.js 14 版本，配置如下：

const nextConfig = {
  experimental: {
    serverComponentsExternalPackages: ["pdfkit"]
  }
}

而对于 Next.js 15 及更高版本，该配置项已从实验性功能转为正式功能，配置方式变为：

const nextConfig = {
  serverExternalPackages: ["pdfkit"]
}

技术原理

这种解决方案有效的根本原因在于它告诉 Next.js 的打包系统：

1. PDFKit 应该被视为服务端专用的外部依赖
2. 不要尝试对 PDFKit 进行深度打包或优化
3. 保留 PDFKit 原有的文件结构和依赖关系

通过这种方式，PDFKit 内部的文件引用关系得以保持完整，包括字体度量文件在内的所有必要资源都能在运行时被正确找到。

最佳实践建议

1. 始终使用最新稳定版的 Next.js 和 PDFKit
2. 根据使用的 Next.js 版本选择正确的配置方式
3. 在开发环境和生产环境都进行充分测试
4. 考虑将 PDF 生成功能封装为独立的 API 路由，而不是放在前端组件中
5. 对于复杂的 PDF 生成需求，可以考虑使用专门的微服务来处理

通过以上方法，开发者可以避免 Helvetica.afm 文件缺失的问题，同时构建出更加健壮和可维护的 PDF 生成功能。