Multer报LIMIT_UNEXPECTED_FILE错误：多图上传接口调试异常

问题场景 #

开发房产网站多图上传表单时，用Postman以form-data格式向http://localhost:8080/api/files/upload上传两张图片，触发如下错误：

RangeError [ERR_HTTP_INVALID_STATUS_CODE]: Invalid status code: LIMIT_UNEXPECTED_FILE
    at new NodeError (node:internal/errors:393:5)
    at ServerResponse.writeHead (node:_http_server:343:11)
    at ServerResponse._implicitHeader (node:_http_server:334:8)
    at write_ (node:_http_outgoing:867:9)
    at ServerResponse.end (node:_http_outgoing:977:5)
    at ServerResponse.send (C:\Users\User\Downloads\yedy-react-backend-master\node_modules\express\lib\response.js:232:10)
    at ServerResponse.json (C:\Users\User\Downloads\yedy-react-backend-master\node_modules\express\lib\response.js:278:15)
    at C:\Users\User\Downloads\yedy-react-backend-master\server.js:35:7
    at Layer.handle_error (C:\Users\User\Downloads\yedy-react-backend-master\node_modules\express\lib\router\layer.js:71:5)
    at trim_prefix (C:\Users\User\Downloads\yedy-react-backend-master\node_modules\express\lib\router\index.js:326:13)

相关代码配置如下：

路由总配置 #

app.use("/api/files", imageRoutes); // => /api/files/

图片控制器（images-controllers.js） #

const fs = require("fs")

const uploadImage = (req, res, next) => {
    const files = req.files;

    if (! files) {
       res.status(400).send('Please choose files');
       return;        
    }
    // convert images into base64 encoding
    let imgArray = files.map((file) => {
        let img = fs.readFileSync(file.path)

        return encode_image = img.toString('base64')
    })
    let result = imgArray.map((src, index) => { // create object to store data in the collection
        let finalImg = {
            filename: files[index].originalname,
            contentType: files[index].mimetype,
            imageBase64: src
        }

        let newUpload = new UploadModel(finalImg);

        return newUpload.save().then(() => {
            return {msg: `${
                    files[index].originalname
                } Uploaded Successfully...!`}
        }).catch(error => {
            if (error) {
                if (error.name === 'MongoError' && error.code === 11000) {
                    return Promise.reject({error: `Duplicate ${
                            files[index].originalname
                        }. File Already exists! `});
                }
                return Promise.reject({
                    error: error.message || `Cannot Upload ${
                        files[index].originalname
                    } Something Missing!`
                })
            }
        })
    });

    Promise.all(result).then(msg => { // res.json(msg);
        res.redirect('/')
    }).catch(err => {
        res.json(err);
    })
}

exports.uploadImage = uploadImage;

Multer配置（multer.js） #

const multer = require('multer');

// set storage
var storage = multer.diskStorage({
    destination : function ( req , file , cb ){
        cb(null, 'uploads')
    },
    filename : function (req, file , cb){
        // image.jpg
        var ext = file.originalname.substr(file.originalname.lastIndexOf('.'));

        cb(null, file.fieldname + '-' + Date.now() + ext)
    }
})

module.exports = store = multer({ storage : storage })

图片路由（image-routes.js） #

const express = require("express");
const router = express.Router()
const store = require("../middleware/multer")

const imagesController = require("../controllers/images-controllers");

router.post('/upload', store.array('images', 12), imagesController.uploadImage)

module.exports = router;

错误原因分析 #

1. 文件字段名不匹配：Multer配置的是接收images字段的文件数组，但Postman上传时使用的字段名不是images，Multer会抛出LIMIT_UNEXPECTED_FILE错误，表示接收到了未配置的文件字段。
2. 全局错误处理不当：server.js中的全局错误处理中间件错误地将Multer抛出的错误信息（字符串类型）作为HTTP状态码传入res.status()，而该方法仅接受数字类型的状态码，因此触发ERR_HTTP_INVALID_STATUS_CODE。

解决方案 #

1. 修正Postman上传字段名 #

在Postman的form-data表单中，确保所有上传文件的字段名统一设置为images（注意大小写敏感）。

2. 完善Multer错误捕获与处理 #

修改image-routes.js，在Multer中间件后添加错误捕获逻辑，提前处理Multer相关错误：

const express = require("express");
const router = express.Router()
const store = require("../middleware/multer")
const multer = require('multer'); // 引入multer用于错误判断

const imagesController = require("../controllers/images-controllers");

router.post('/upload', (req, res, next) => {
  // 手动调用multer中间件并捕获错误
  store.array('images', 12)(req, res, (err) => {
    if (err instanceof multer.MulterError) {
      // 处理Multer自身错误
      let errorMsg = '';
      if (err.code === 'LIMIT_UNEXPECTED_FILE') {
        errorMsg = '上传字段名错误，请使用「images」作为文件字段名';
      } else {
        errorMsg = err.message;
      }
      return res.status(400).json({ error: errorMsg });
    } else if (err) {
      // 其他错误交给全局中间件处理
      return next(err);
    }
    // 无错误时执行控制器逻辑
    imagesController.uploadImage(req, res, next);
  });
})

module.exports = router;

3. 修复全局错误处理中间件 #

修改server.js中的错误处理逻辑，确保状态码为数字类型：

// 全局错误处理中间件
app.use((err, req, res, next) => {
  // 处理Multer错误
  if (err instanceof multer.MulterError) {
    return res.status(400).json({ error: err.message });
  }
  // 处理其他错误
  const statusCode = err.statusCode || 500;
  res.status(statusCode).json({
    error: err.message || '服务器内部错误'
  });
});

4. 优化控制器的文件存在判断 #

原控制器中if (!files)的判断无法识别空数组（上传0个文件的情况），修改为：

if (!files || files.length === 0) {
  res.status(400).send('Please choose files');
  return;        
}

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