Multer 2.2 + Express 5 + TypeScript 教程导航

本系列基于 Multer 官方仓库 和当前项目安装的 multer@2.2.0 编写。

Multer 是处理 multipart/form-data 的 Express 中间件，底层使用 Busboy 解析 multipart 流。它负责接收文件，不负责判断文件一定安全，也不负责长期文件管理。

学习路线

  1. 01 multipart/form-data 与基础上传
  2. 02 上传 API 与多文件
  3. 03 存储、元数据与下载
  4. 04 文件名和路径安全
  5. 05 文件验证与尽早拒绝
  6. 06 错误处理、清理与一致性
  7. 07 TypeScript 与 Express 工程整合
  8. 08 生产环境最佳实践

上传安全的核心心智模型

客户端 FormData
  → Nginx 整体请求限制
  → Multer/Busboy 解析 multipart
  → limits 与 fileFilter
  → 临时隔离存储
  → Magic Number/解码/病毒扫描
  → 正式存储
  → MySQL 保存元数据和业务关系

必须始终认为下面的数据不可信：

file.originalname
file.mimetype
文件扩展名
multipart 文本字段
文件内容

高频 API

multer(options)
upload.single(fieldname)
upload.array(fieldname, maxCount)
upload.fields(fields)
upload.none()
multer.diskStorage()
multer.memoryStorage()
limits
fileFilter
multer.MulterError

.any() 虽然存在，但不应作为全局中间件，也不应成为普通接口的默认方案。

三种不同的名称

一个文件通常需要区分：

名称 用途
original_name 用户下载时希望看到的名称
storage_key 服务器或对象存储中的随机安全名称
file_id 业务 API 使用的数据库 ID

不要把用户文件名直接当成磁盘路径或对象存储 key。

官方参考