Transformers.js 在 Next.js 和 React 项目中的常见问题及解决方案

Transformers.js 是一个强大的 JavaScript 库，它允许开发者在浏览器和 Node.js 环境中运行 Hugging Face 的 Transformer 模型。然而，在将库升级到 v3 版本后，许多开发者在使用 Next.js 和 Create React App (CRA) 项目时遇到了构建错误。

问题现象

当开发者尝试在 Next.js 或 React 项目中使用 Transformers.js v3 时，通常会遇到以下错误信息：

ERROR in ../../node_modules/@huggingface/transformers/dist/transformers.js 42256:34-64
Module not found: Error: Can't resolve './' in '/node_modules/@huggingface/transformers/dist'

这个错误表明 Webpack 在解析模块路径时遇到了问题，特别是在处理 Transformers.js 的打包输出时。

根本原因

经过分析，这个问题主要源于 Transformers.js v3 的模块导出方式和 Webpack 的解析机制之间的不兼容性。具体来说：

1. 模块路径解析问题：Webpack 无法正确解析库内部的相对路径引用
2. 构建工具差异：不同构建工具（Webpack、Vite 等）对模块解析的实现方式不同
3. 版本兼容性：从 v3.0.0-alpha.10 开始引入的变化导致了这个问题

解决方案

对于 Next.js 项目

Next.js 提供了几种解决方案：

1. 使用 serverExternalPackages 配置（推荐）： 在 next.config.js 中添加以下配置：

   const nextConfig = {
     output: "standalone",
     serverExternalPackages: ["@huggingface/transformers"]
   };
   

2. Webpack 别名配置： 如果上述方法不适用，可以尝试添加 Webpack 别名：

   webpack(config, { isServer }) {
     config.resolve.alias['@huggingface/transformers'] = 
       path.resolve(__dirname, 'node_modules/@huggingface/transformers');
     return config;
   }
   

3. 额外配置： 有时还需要禁用某些不必要的模块：

   config.resolve.alias = {
     ...config.resolve.alias,
     sharp$: false,
     'onnxruntime-node$': false
   };
   

对于 Create React App (CRA) 项目

由于 CRA 隐藏了 Webpack 配置，解决方案较为复杂：

1. 推荐方案：使用 CDN 引入

   import { pipeline } from 'https://cdn.jsdelivr.net/npm/@huggingface/transformers@3.3.1';
   

2. 高级方案：弹出(eject) CRA 配置

   1. 运行 npm run eject
   2. 在生成的 webpack 配置中添加别名：

   "@huggingface/transformers": path.resolve(
     __dirname.replace("/config", ""),
     "node_modules/@huggingface/transformers"
   )
   

最佳实践建议

1. 版本选择：如果可能，暂时使用 v3.0.0-alpha.9 版本可以避免这个问题
2. 构建工具：考虑迁移到 Vite，它对 Transformers.js 的支持更好
3. 环境隔离：在服务端使用 Transformers.js 时，确保正确配置外部依赖
4. 持续关注：随着库的更新，这些问题可能会被官方修复

技术背景

这个问题的出现与 JavaScript 模块系统的复杂性有关。Webpack 和 Node.js 对模块解析有不同的规则，当库的打包方式与项目的构建工具不匹配时，就会出现路径解析问题。Transformers.js 作为一个包含 WASM 和本地依赖的复杂库，特别容易遇到这类问题。

理解这些解决方案背后的原理，有助于开发者在遇到类似问题时能够快速定位和解决。随着 JavaScript 生态系统的不断演进，这类问题有望通过更好的工具链支持和标准化得到缓解。