Express文件表单解析中间件 Multer简介

前言

Express中最常使用的form解析中间件就是body-parser了,但是它明确表示不会支持multipart/form-data类型的表单.

所以在body-parser官方文档中提供了如下的几个支持multipart/form-data类型的中间件的链接,或者只支持multipart/form-data解析的中间件链接.

名称&地址	周下载量	stars
busboy	426,278	1448
multipart	240,921	993
formidable	1,390,361	4735
multer	284,926	5860

统计截止到2018年12月26日

multer依赖busboy所以所以busboy的实际直接下载数量应该要减少28万?.

什么是multipart/form-data类型的表单?

最直观的解释就是支持上传文件的form表单,如果不使用JavaScript中创建的话,显式的html声明如下:

<form action="/profile" method="post" enctype="multipart/form-data">
          <input type="file" name="file"/>
          <input type="submit" value="submit">
        </form>

上例子中的<input type="file" name="file" >在页面中的显示就是为一个按钮点击后可以进行文件选择.

其次input可以添加multiple="multiple"属性,这个时候打开的文件选择框会允许多选文件.

总结一下有如下几种关系:

• 一个name对应多个文件
• 一个name对应一个文件
• 多个name对应多个单个文件
• 多个name对应多个文件

顺便说一句multer有中文文档.

正文

特点

• multer只会解析form设置为enctype="multipart/form-data"表单.
• multer可以定制存储引擎
• multer会将上传的信息以及内容挂载到request对象上
  – request.body 保存文本内容
  – request.file 保存单个文件信息以及对应内容(内存存储模式)
  – request.files 保存多个文件信息以及对应的内容(内存存储模式)

基本工作流程

1. 创建一个multer实例
2. 使用该实例上提供的不同方法获取不同功能的中间件
3. 放入到对应的路由中

上传单个文件实例

引入multer和Express

const
    express = require('express'),
    multer = require('multer'),
    app = express();

传入配置参数

  const upload = multer({dest:'/uploads'});

注意：dest参数指定了文件输出的位置,可以详细指定文件输出以及储存后面会将.

使用multer中间件传递单个文件

app.get('/',(request,response)=>{

    console.log('get.request.body',request.body);
    console.log('get.request.file',request.file);
    console.log('get.request.files',request.files);

    response.send('<form action="/" enctype="multipart/form-data" method="post">'+
        '<input type="text" name="title"><br>'+
        '<input type="file" name="upload" multiple="multiple"><br>'+
        '<input type="submit" value="Upload">'+
        '</form>')

});

app.post('/',upload.single('upload'),(request,response)=>{

    console.log('post.request.body',request.body);
    console.log('post.request.file',request.file);
    console.log('post.request.files',request.files);

    response.redirect('/');

});

app.listen(8888,()=>{

   console.log('express正在监听8888端口');

});

这个例子中我们监听了根路径,分别处理两种不同的请求方式,针对get我们响应表单,针对post我们接受上传的内容.

注意:upload.single('upload')意思是高速multer只接收name是upload的单个文件.

注意:这个例子中input是可以进行多选的,也就是说后端指定了文件数量为1但是页面依然上传了多个,这个时候multer会报错.

注意:dest指定的路径为upload/会将文件保存到根路径下的upload文件夹中,对于windows系统来说是在运行这个应用对应的盘符下例如F:\uploads\

这个例子中我填写了一个文本内容,同时上传了一个文件,输出结果如下:

post.request.body { title: 'hello world' }
post.request.file { fieldname: 'upload',
  originalname: '硬盘坏道扫描及修复工具Victoria.7z',
  encoding: '7bit',
  mimetype: 'application/octet-stream',
  destination: '/uploads',
  filename: '6bdfc0df998d72e6232d60f790f47ef8',
  path: '\\uploads\\6bdfc0df998d72e6232d60f790f47ef8',
  size: 1033375 }

上传多个文件实例

const
    express = require('express'),
    multer = require('multer'),
    app = express();

const upload = multer({dest:'/uploads'});

app.get('/',(request,response)=>{

    console.log('get.request.body',request.body);
    console.log('get.request.file',request.file);
    console.log('get.request.files',request.files);

    response.send('<form action="/" enctype="multipart/form-data" method="post">'+
        '<input type="text" name="title"><br>'+
        '<input type="file" name="upload"><br>'+ // 此处有两个相同name的input
        '<input type="file" name="upload"><br>'+
        '<input type="submit" value="Upload">'+
        '</form>')

});

app.post('/',upload.array('upload'),(request,response)=>{ // 注意此处使用的中间件和上例中不同

    console.log('post.request.body',request.body);
    console.log('post.request.file',request.file);
    console.log('post.request.files',request.files);

    response.redirect('/');

});

app.listen(8888,()=>{

   console.log('express正在监听8888端口');

});

在这个例子的表单中有两个同名的name都是文件类型,这次使用array的方式来进行接受,控制台输出内容如下:

post.request.body { title: 'hello world' }
post.request.file undefined
post.request.files [ { fieldname: 'upload',
    originalname: '硬盘坏道扫描及修复工具Victoria.7z',
    encoding: '7bit',
    mimetype: 'application/octet-stream',
    destination: '/uploads',
    filename: '71ed2ac4299d43a30f5c13892f33e51b',
    path: '\\uploads\\71ed2ac4299d43a30f5c13892f33e51b',
    size: 1033375 },
  { fieldname: 'upload',
    originalname: '新建文本文档.txt',
    encoding: '7bit',
    mimetype: 'text/plain',
    destination: '/uploads',
    filename: '190bde8fcdd08d57648ffb243607ed9d',
    path: '\\uploads\\190bde8fcdd08d57648ffb243607ed9d',
    size: 218 } ]

在上面的例子中删除掉一个input,将剩余的input添加multiple属性用于多选,页面中在选择文件框中选择多个文件也是可以顺利通过.

其余的方法

除了上方提到的multer.single方法外还有其他的几种方法.

• array(name:string,maxcount?:number) 根据name限制上传文件的最大个数
• fields(fields:object) 自定义限制规则
• none() 只保留文本信息
• any() 允许任意类型通过,文件数组将保存在 req.files

实际上它们都可以视为fields方法的包装,源码如下:

Multer.prototype.single = function (name) {
  return this._makeMiddleware([{ name: name, maxCount: 1 }], 'VALUE')
}

Multer.prototype.array = function (name, maxCount) {
  return this._makeMiddleware([{ name: name, maxCount: maxCount }], 'ARRAY')
}

Multer.prototype.fields = function (fields) {
  return this._makeMiddleware(fields, 'OBJECT')
}

Multer.prototype.none = function () {
  return this._makeMiddleware([], 'NONE')
}

Multer.prototype.any = function () {
  function setup () {
    return {
      limits: this.limits,
      preservePath: this.preservePath,
      storage: this.storage,
      fileFilter: this.fileFilter,
      fileStrategy: 'ARRAY'
    }
  }

  return makeMiddleware(setup.bind(this))
}

常用API一览

来自中文文档:

multer(opts)

Multer 接受一个 options 对象，其中最基本的是 dest 属性，这将告诉 Multer 将上传文件保存在哪。如果你省略 options 对象，这些文件将保存在内存中，永远不会写入磁盘。

为了避免命名冲突，Multer 会修改上传的文件名。这个重命名功能可以根据您的需要定制。

以下是可以传递给 Multer 的选项。

Key	Description
dest or storage	在哪里存储文件
fileFilter	文件过滤器，控制哪些文件可以被接受
limits	限制上传的数据
preservePath	保存包含文件名的完整文件路径

fileFilter

设置一个函数来控制什么文件可以上传以及什么文件应该跳过，这个函数应该看起来像这样：

function fileFilter (req, file, cb) {

  // 这个函数应该调用 `cb` 用boolean值来
  // 指示是否应接受该文件

  // 拒绝这个文件，使用`false`，像这样:
  cb(null, false)

  // 接受这个文件，使用`true`，像这样:
  cb(null, true)

  // 如果有问题，你可以总是这样发送一个错误:
  cb(new Error('I don\'t have a clue!'))

}

错误处理机制

当遇到一个错误，multer 将会把错误发送给 express。你可以使用一个比较好的错误展示页 (express标准方式)。

如果你想捕捉 multer 发出的错误，你可以自己调用中间件程序。如果你想捕捉 Multer 错误，你可以使用 multer 对象下的 MulterError 类 (即 err instanceof multer.MulterError)。

var multer = require('multer')
var upload = multer().single('avatar')

app.post('/profile', function (req, res) {
  upload(req, res, function (err) {
    if (err instanceof multer.MulterError) {
      // 发生错误
    } else if (err) {
      // 发生错误
    }

    // 一切都好
  })
})

磁盘存储引擎 (DiskStorage)

磁盘存储引擎可以让你控制文件的存储。

var storage = multer.diskStorage({
  destination: function (req, file, cb) {
    cb(null, '/tmp/my-uploads')
  },
  filename: function (req, file, cb) {
    cb(null, file.fieldname + '-' + Date.now())
  }
})

var upload = multer({ storage: storage })

有两个选项可用，destination 和 filename。他们都是用来确定文件存储位置的函数。

destination 是用来确定上传的文件应该存储在哪个文件夹中。也可以提供一个 string (例如 '/tmp/uploads')。如果没有设置 destination，则使用操作系统默认的临时文件夹。

注意: 如果你提供的 destination 是一个函数，你需要负责创建文件夹。当提供一个字符串，multer 将确保这个文件夹是你创建的。

filename 用于确定文件夹中的文件名的确定。 如果没有设置 filename，每个文件将设置为一个随机文件名，并且是没有扩展名的。

注意: Multer 不会为你添加任何扩展名，你的程序应该返回一个完整的文件名。

每个函数都传递了请求对象 (req) 和一些关于这个文件的信息 (file)，有助于你的决定。

注意 req.body 可能还没有完全填充，这取决于向客户端发送字段和文件到服务器的顺序。

内存存储引擎 (MemoryStorage)

内存存储引擎将文件存储在内存中的 Buffer 对象，它没有任何选项。

var storage = multer.memoryStorage()
var upload = multer({ storage: storage })

当使用内存存储引擎，文件信息将包含一个 buffer 字段，里面包含了整个文件数据。

警告: 当你使用内存存储，上传非常大的文件，或者非常多的小文件，会导致你的应用程序内存溢出。

filefilter和filename还有路由触发的顺序

const
    express = require('express'),
    multer = require('multer'),
    app = express();

const storage = multer.diskStorage({
    destination:__dirname, // 保存到当前目录
    filename(request,file,callback){

        console.log('filename:',file);

        callback(null,'newfilename');// 修改上传的文件名称
    }
});


const upload = multer({
    dest:'/uploads',
    fileFilter(request,file,cb){

        console.log('fileFilter:',file);

        cb(null,true);

    },
    limits:{
        fileSize:100000 // 限制上传文件大小为100000字节
    },
    storage // 使用默认的储存器
});

最后触发的顺序为:

1. filefilter
2. filename
3. 我们定义的路由