Next.js API路由导入nodemailer时出现多个报错如何解决

问题现象 #

• 搭建pages/api/sendEmail API端点实现nodemailer发信能力，通过let nodemailer = require('nodemailer')引入依赖时，触发Can't resolve 'fs'报错
• 该类报错常见成因是代码在前端环境执行，但相关逻辑明确写在服务端运行的API路由文件中
• 参考网上方案修改next.config.js修复后，触发新的报错：

Uncaught TypeError: util__WEBPACK_IMPORTED_MODULE_3__.TextEncoder is not a constructor

• 相同实现逻辑在多个公开教程中可正常运行，本地环境API路由无法正常加载nodemailer包

根因说明 #

• Can't resolve 'fs'报错本质是Next.js打包器误将nodemailer判定为需要打到前端bundle的客户端依赖，fs是Node.js原生模块，浏览器环境不存在该模块
• 后续出现的TextEncoder报错，是因为修改next.config.js时错误添加了Node原生模块的浏览器polyfill/mock配置（比如给webpack加fallback: { fs: false, util: ... }这类规则），这些polyfill实现不完整，会直接打断服务端代码的正常运行
• 最常见的依赖误判触发原因：包含nodemailer引入的服务端逻辑文件，被前端页面/组件直接import引用，打包器会顺着引用链把服务端依赖打进客户端包

修复步骤 #

• 清空next.config.js中所有针对Node原生模块（fs、util、path等）的webpack fallback、mock配置，Pages Router下的API路由默认运行在Node.js环境，不需要额外做浏览器兼容polyfill，这类配置只会干扰服务端依赖的正常打包
• 梳理代码引用链路，确保nodemailer相关逻辑仅在服务端执行：
  • 前端侧仅通过HTTP请求（fetch/axios）调用/api/sendEmail接口，禁止直接import API路由文件或包含nodemailer引入的服务端工具文件
  • 若需要抽离发信公共逻辑，可将文件放在pages/api目录内，或给文件添加.server.js/.server.ts后缀，Next.js会强制这类文件仅在服务端打包，不会进入客户端bundle
• 确认nodemailer已正确安装到项目生产依赖中：

npm install nodemailer

• 清除Next.js打包缓存后重启项目，避免旧配置残留导致报错复现：

rm -rf .next
npm run dev

注意：不要通过mock Node原生模块的方式解决Can't resolve 'fs'报错，这类方案是纯前端项目兼容Node包的临时方案，在服务端API场景下用会直接破坏运行环境，正确修复思路是切断服务端依赖到客户端代码的引用链路。

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