multer

概述

multer 是 Express 生态中最流行的文件上传处理中间件，专注于处理 multipart/form-data 格式的文件上传。支持文件大小限制、类型过滤、存储位置配置、单/多文件上传等。

安装：

npm install multer

核心函数

创建实例

const multer = require('multer')

// 内存存储（文件存在 Buffer 中）
const upload = multer({ dest: 'uploads/' })

// 磁盘存储（可控制文件名和路径）
const storage = multer.diskStorage({
  destination: (req, file, cb) => cb(null, 'uploads/avatars/'),
  filename: (req, file, cb) => {
    const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9)
    const ext = path.extname(file.originalname)
    cb(null, file.fieldname + '-' + uniqueSuffix + ext)
  }
})
const upload = multer({ storage })

上传方式

upload.single('avatar')          // 单文件
upload.array('photos', 10)       // 同字段多文件
upload.fields([                  // 多字段
  { name: 'avatar', maxCount: 1 },
  { name: 'gallery', maxCount: 5 }
])
upload.any()                      // 任意字段
upload.none()                     // 无文件

路由使用

app.post('/profile', upload.single('avatar'), (req, res) => {
  // req.file — 单文件信息
  // { fieldname, originalname, mimetype, size, path, ... }
  res.json({ success: true, file: req.file.filename })
})

app.post('/photos', upload.array('photos', 10), (req, res) => {
  // req.files — 文件数组
  res.json({ count: req.files.length })
})

配置选项

const upload = multer({
  storage,
  limits: {
    fileSize: 5 * 1024 * 1024,   // 单文件最大 5MB
    files: 5,                    // 最多文件数
    fieldSize: 2 * 1024 * 1024  // 单字段最大
  },
  fileFilter: (req, file, cb) => {
    const allowed = ['image/jpeg', 'image/png', 'image/gif']
    if (allowed.includes(file.mimetype)) cb(null, true)
    else cb(new Error('只允许上传 JPG/PNG/GIF 图片'), false)
  }
})

错误处理

app.use((err, req, res, next) => {
  if (err instanceof multer.MulterError) {
    if (err.code === 'LIMIT_FILE_SIZE') return res.status(400).json({ error: '文件过大' })
    if (err.code === 'LIMIT_FILE_COUNT') return res.status(400).json({ error: '文件数量超限' })
  }
  res.status(500).json({ error: err.message })
})

常见问题