如何在Next.js服务端API中添加uploadFile.single文件上传中间件

Next.js 的 Pages Router API 路由默认会自动解析请求体，会消费掉 multipart/form-data 的原始流，导致 multer 无法读取上传文件，必须先关闭默认的 body 解析，再适配 multer 中间件即可，不需要修改你原本的 multer 配置。

核心实现步骤 #

• 在对应API路由文件中导出配置，关闭Next.js内置的bodyParser
• 复用原有Express项目中uploadFile的multer配置，存储规则、大小限制、文件过滤逻辑都可以原样迁移
• 写一个简易的中间件执行包装函数，Next.js的req/res对象兼容Express中间件的入参格式，只需要把中间件包成Promise形式就能在handler里用await执行

完整可运行代码 #

import type { NextApiResponse } from 'next'
import multer from 'multer'

// 直接替换成你原本Express项目里的uploadFile配置即可，不需要改逻辑
const uploadFile = multer({
  storage: multer.diskStorage({
    destination: (req, file, cb) => cb(null, './public/uploads'), // 你原来配置的上传存储路径
    filename: (req, file, cb) => cb(null, `${Date.now()}-${file.originalname}`) // 你原来配置的文件命名规则
  }),
  limits: { fileSize: 10 * 1024 * 1024 } // 你原来配置的大小、格式限制
})

// 包装中间件为Promise形式，适配Next.js的async/await写法
function runMiddleware(req: any, res: NextApiResponse, middlewareFn: Function) {
  return new Promise((resolve, reject) => {
    middlewareFn(req, res, (result: any) => {
      if (result instanceof Error) return reject(result)
      resolve(result)
    })
  })
}

// 关键配置：关闭Next.js默认请求体解析，否则multer拿不到原始文件流
export const config = {
  api: {
    bodyParser: false
  }
}

type Data = {
  message: string
  // 自行补充你的接口返回类型定义
}

export default async function handler(req: any, res: NextApiResponse<Data>) {
  if (req.method !== 'POST') {
    res.status(405).json({ message: 'Method Not Allowed' })
    return
  }

  try {
    // 执行单文件上传中间件，和Express中uploadFile.single('file')效果完全一致，字段名保持为'file'
    await runMiddleware(req, res, uploadFile.single('file'))
    
    // 中间件执行完后，上传的文件信息会挂载到req.file上，和Express用法完全一致
    // 下方直接写你原有的业务逻辑即可，比如解析Excel、数据入库等
    console.log('已接收上传文件：', req.file)
    
    res.status(200).json({ message: '上传成功' })
  } catch (error) {
    res.status(500).json({ message: '上传失败' })
  }
}

常见问题排查 #

• 如果始终拿不到req.file，优先检查是否配置了bodyParser: false，这是最高发的问题
• 如果你用的是Next.js 13+的App Router（不是export default handler的写法），这套方案不适用，需要换App Router对应的formData解析方法
• req.file的字段结构、req.body携带的其他表单字段，和Express环境下的返回结构完全一致，不需要调整原有业务解析逻辑

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