Next.js文件上传API故障：发送文件无响应无日志，求排查方法

问题场景 #

我在Next.js的/pages/api目录下创建了upload.js接口，用于将接收的文件上传至AWS，近期该接口突然失效，添加日志后终端和浏览器控制台均无任何反馈。为此我新建了一个极简API：

import formidable from "formidable";

export default async function handler(req, res) {
    if (req.method === "POST") {
        console.log('POST')
        return res.status(200).send('Finished POST')
    }
    return res.status(200).send('Hello World')
}

export const config = {
    api: {
        bodyParser: false,
    },
};

该API处理普通POST请求时可正常响应并输出日志，但发送文件时，Postman一直处于「发送请求」状态，始终无法完成，且无控制台日志输出。

排查与调试方法 #

一、请求端验证 #

• 检查Postman配置：确认请求为POST方法，Body选择form-data，文件字段名无特殊字符，文件选择正常，超时时间设置合理。同时用curl命令模拟上传，排除客户端工具问题：

  curl -X POST -F "file=@/本地测试文件路径" http://localhost:3000/api/你的接口名
  

• 抓包验证请求到达情况：用tcpdump或Wireshark抓取服务器端口的网络包，确认文件上传请求是否真的发送到服务器。若抓不到请求，说明是客户端到服务器的网络/请求配置问题；若抓到请求但未进入API逻辑，说明请求被Next.js路由或中间件拦截。

二、Next.js配置与中间件排查 #

• 确认bodyParser: false生效：在API开头打印req.body，若有值则说明bodyParser未被禁用，formidable无法处理已解析的请求体。检查next.config.js的全局body配置，或是否有自定义中间件提前解析了请求体。
• 排查全局中间件：若项目使用middleware.js，临时注释中间件后测试文件上传，排查是否是中间件在处理multipart请求时卡住。

三、Formidable核心问题处理 #

• 显式处理multipart请求：你的极简API仅引入了formidable但未实际解析请求，禁用bodyParser后，服务器会一直等待未解析的multipart请求体，导致请求挂起。修改代码显式解析：

  import formidable from "formidable";
  
  export default async function handler(req, res) {
      if (req.method === "POST") {
          console.log('POST received');
          const form = formidable({});
          try {
              const [fields, files] = await form.parse(req);
              console.log('解析的字段:', fields);
              console.log('解析的文件:', files);
              return res.status(200).send('Finished POST');
          } catch (err) {
              console.error('解析错误:', err);
              return res.status(500).send('Parse error');
          }
      }
      return res.status(200).send('Hello World');
  }
  
  export const config = {
      api: {
          bodyParser: false,
      },
  };
  

• 检查版本兼容性：确认formidable版本与Next.js版本兼容，formidable v3+为ES模块，v2为CommonJS，若导入方式错误会导致解析失败，可尝试降级或升级版本测试。

四、服务器与环境限制排查 #

• 监控进程状态：文件上传时用top/htop查看Node.js进程的CPU和内存占用，排查是否因文件过大导致内存溢出或进程阻塞，也可在代码中加入console.log(process.memoryUsage())打印内存情况。
• 调整文件大小限制：在formidable配置中显式设置最大文件尺寸，同时检查Next.js全局配置是否有相关限制：

  const form = formidable({ maxFileSize: 10 * 1024 * 1024 }); // 限制为10MB
  

• 排查AWS依赖问题（针对原upload.js）：测试AWS SDK的单独上传逻辑，用本地文件测试S3上传是否正常，排查是否是凭证过期、权限变更或SDK版本冲突导致原接口失效。

五、增强日志与调试 #

• 添加请求体传输日志：在API入口处添加事件监听，查看请求体是否完整传输：

  req.on('data', chunk => console.log('接收数据块大小:', chunk.length));
  req.on('end', () => console.log('请求体传输完成'));
  req.on('error', err => console.error('请求传输错误:', err));
  

• 启用Next.js调试模式：启动项目时添加环境变量，查看框架层面的日志：

  NODE_ENV=development DEBUG=next:* npm run dev
  

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