Node.js使用Multer中间件实现文件上传详解

作者：墨池时间：2026-10-22 08:49:02浏览：274

本文介绍如何在Node.js项目中利用Multer中间件处理multipart/form-data文件上传。详细讲解如何配置diskStorage自定义存储路径与文件名，区分single与array方法处理单/多文件，并通过fileFilter和limits参数实现文件类型、大小及数量的过滤控制，包含完整的错误捕获示例。

Node.js Multer文件上传配置与错误处理指南

在Node.js项目开发过程中，经常需要实现文件上传功能。经过查阅相关资料，可以使用处理 multipart/form-data 类型表单数据的Express中间件，该工具能便捷地将表单中的文件数据保存至服务器端。

介绍

简单的用法

定义存储器

Multer作为Express的一个中间件，我们可以很方便的自定义上传的文件目录以及保存的文件名。先看一个最简单的用法， demo1地址：


var express = require('express');
var multer = require('multer');
var app = express();

var upload = multer({
  storage: multer.diskStorage({
    destination: function (req, file, cb){
      cb(null, './uploads/');
    },
    filename: function (req, file, cb){
      //file.originalname上传文件的原始文件名
      var changedName = (new Date().getTime())+'-'+file.originalname;
      cb(null, changedName);
    }
  })
});

首先创建一个upload对象，其中destination函数用于指定上传文件存储的文件夹路径；filename函数用于修改上传文件在服务器上的保存名称，此处通过添加时间戳来简单区分不同文件。这两个函数均通过回调方式实现。每次执行上传操作时，系统会调用这两个函数；若涉及多文件上传，则多次调用，且调用顺序为先destination后filename。

在这两个回调函数中，均存在一个file对象，代表当前正在上传的文件，该对象包含以下属性：

fieldname：上传的字段名
originalname：上传的文件名
encoding：文件的编码类型
mimetype：文件的MIME类型

定义路由回调


//单个文件上传
app.post('/upload/single',upload.single('singleFile'),(req,res)=>{
  console.log(req.file);
  res.json({
    code: '0000',
    type:'single',
    originalname: req.file.originalname
  })
});

//多个文件上传
app.post('/upload/multer',upload.array('multerFile'),(req,res)=>{
  console.log(req.files);
  let fileList = [];
  req.files.map((elem)=>{
    fileList.push({
      originalname: elem.originalname
    })
  });
  res.json({
    code: '0000',
    type:'multer',
    fileList:fileList
  });
});

在Express中定义路由的回调函数时，将配置好的upload对象作为中间件引入。针对单个文件上传使用single方法，针对多个文件上传使用array方法，这两种方法均需传入前端页面中定义的字段名。

在路由的回调函数中，request对象已具备file属性（针对单个文件上传）或files属性（针对多个文件上传），其中files属性为数组，数组内每个对象包含以下属性：

fieldname：上传的字段名
originalname：上传的文件名
encoding：文件的编码类型
mimetype：文件的MIME类型
destination：存储的目录（和destination回调函数中的目录名一致）
filename：保存的文件名（和filename回调函数中的文件名一致）
path：保存的相对路径
size：文件的大小（单位：字节byte）

对比可知，路由回调函数中的file对象比diskStorage中的file对象多出了几个属性。这是因为在diskStorage阶段文件尚未保存，仅能获取文件的基本属性；而在路由回调阶段，文件已保存至服务器，因此文件的保存路径及大小均为已知状态。

过滤文件上传

在文件上传过程中，有时会遇到不需要的文件类型，此时需要对这些文件进行过滤。demo2地址。

文件类型过滤


var upload = multer({
  //...其他代码
  fileFilter: function(req, file, cb){
    if(file.mimetype == 'image/png'){
      cb(null, true)
    } else {
      cb(null, false)
    }
  }
});

在定义存储器时，新增fileFilter函数用于过滤不需要的文件。在回调函数中传入true或false以决定是否保存文件；若传入false，则不会调用destination和filename函数。

文件大小和数量过滤


var upload = multer({
  //...其他代码
  limits:{
    //限制文件大小10kb
    fileSize: 10*1000,
    //限制文件数量
    files: 5
  }
});

在定义存储器时，新增limits对象以控制上传的相关信息，其包含以下属性：

fieldNameSize：field 名字最大长度，默认值：100 bytes
fieldSize：field 值的最大长度，默认值：1MB
fields：非文件 field 的最大数量
fileSize：在multipart表单中, 文件最大长度 (字节单位)
files：在multipart表单中, 文件最大数量
parts：在multipart表单中, part传输的最大数量(fields + files)

此处将fileSize的值设置得较小，设为10kb以便测试效果。但需注意，上传文件很容易超过10KB限制从而引发报错，因此需要在路由回调中对错误情况进行捕获处理。


//单个文件上传
let singleUpload = upload.single('singleFile');
app.post('/upload/single',(req,res)=>{
  singleUpload(req,res,(err)=>{
    if(!!err){
      console.log(err.message)
      res.json({
        code: '2000',
        type:'single',
        originalname: '',
        msg: err.message
      })
      return;
    }
    if(!!req.file){
      res.json({
        code: '0000',
        type:'single',
        originalname: req.file.originalname,
        msg: ''
      })
    } else {
      res.json({
        code: '1000',
        type:'single',
        originalname: '',
        msg: ''
      })
    }
  });
});

//多个文件上传
let multerUpload = upload.array('multerFile');
app.post('/upload/multer', (req,res)=>{
  multerUpload(req,res,(err)=>{
    if(!!err){
      res.json({
        code: '2000',
        type:'multer',
        fileList:[],
        msg: err.message
      });
    }
    let fileList = [];
    req.files.map((elem)=>{
      fileList.push({
        originalname: elem.originalname
      })
    });
    res.json({
      code: '0000',
      type:'multer',
      fileList:fileList,
      msg:''
    });
  });
});

所有的demo代码都在这个仓库里

以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持本站。

作者最新文章

macOS卸载Node.js指南：区分Homebrew与pkg安装包的处理方式

2026-11-05 11:28:12

JS逆向入门：浏览器Console调试与Node.js环境搭建指南

2026-11-05 10:57:15

Node.js 大版本升级需要注意哪些破坏性变更

2026-11-03 20:35:44

Node.js官网LTS版与Current版有什么区别

2026-11-03 19:33:49

Windows彻底卸载Node.js：清理AppData残留与PATH环境变量

2026-11-03 19:15:35