近日，多位 Node.js 开发者在使用流行文件上传中间件 Multer 时报告了一个令人困惑的异常行为：当应用程序采用 req.files 接收多个文件时，Multer 未能按预期自动创建 uploads 文件夹，导致上传失败；而改用 req.file 接收单个文件时，目录却能自动建立。这一不一致现象引发了社区广泛讨论，并对生产环境中的文件上传功能稳定性构成潜在威胁。

问题现象：同一配置，不同结果

根据开发者反馈，在 Express 应用中配置 Multer 中间件时，通常会指定 dest 或 storage 参数来设置文件存储路径。例如：

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

当使用 upload.single('file') 处理单个文件时，即便 uploads/ 目录不存在，Multer 也能自动创建该文件夹，并将文件正常写入。然而，当改用 upload.array('files', 5) 或 upload.fields([...]) 并借助 req.files 获取文件数组时，若 uploads/ 目录尚未存在，Multer 会直接抛出错误，提示“ENOENT: no such file or directory, open 'uploads/...'”。

这一现象在 Multer 1.4.5-lts.1 及更早版本中均有出现，部分开发者升级至最新版后依然未彻底解决，怀疑与 Multer 内部的文件处理逻辑差异有关。

原因探究：源码中的条件分支漏洞

经过对 Multer 源码的初步分析，问题根源可能隐藏在中间件处理单个文件与多个文件时的代码路径差异中。Multer 内部依赖 busboy 库解析 multipart/form-data 数据。在 single 方法中，Multer 会调用一个特殊的文件流处理函数，该函数在接收流之前尝试调用 fs.mkdir 创建目标目录。而在 array 或 fields 方法中，Multer 复用了另一套文件流处理逻辑，该逻辑在接收多个文件时未能优先调用目录创建函数，而是直接尝试写入，导致目录不存在时抛出异常。

进一步排查显示，Multer 在 DiskStorage 的 _handleFile 方法中确实执行了 mkdir 调用，但该调用仅在 req.file 场景下被正确触发。当处理 req.files 时，_handleFile 被调用的时机或参数传递可能发生偏移，使得 mkdir 操作被跳过。Multer 的 GitHub Issue 列表中已有相关报告，但官方至今未给出明确修复时间表。

解决方案：临时规避与长期建议

对于受此问题困扰的开发者，以下是几种经过验证的临时解决方案：

  1. 手动创建目录：在应用启动时或路由处理前，使用 fs.mkdirSync('uploads', { recursive: true }) 确保目录存在。该方法最为直接，且能避免任何版本兼容性问题。

  2. 统一使用 req.file 并循环发送单个文件：在前端将多个文件逐一通过独立字段上传，后端循环调用 upload.single 处理。此方法虽能规避 bug，但会显著增加网络请求次数，降低性能。

  3. 降级或替换中间件：部分开发者选择降级至 Multer 1.4.4 版本（该版本问题表现较轻），或改用 busboy 原生 API 配合 formidable 等替代方案。但对于已有大量 Multer 依赖的项目，迁移成本较高。

  4. 使用自定义存储引擎：继承 DiskStorage 并重写 _handleFile 方法，确保在写入前调用 fs.mkdir。社区中已有开发者分享了此类补丁代码，可供参考。

预防建议：开发与测试中的目录管理

尽管 Multer 的自动目录创建功能看似便利，但将其作为唯一依赖是危险的。安全实践建议：

  • 所有涉及文件写入的中间件或业务逻辑，都应提前确保目标目录存在，并写入 startup 脚本或应用初始化代码中。
  • 在测试环境中模拟目录缺失的场景，验证应用的行为是否符合预期（如优雅报错、自动创建等）。
  • 关注 Multer 官方版本更新，一旦修复该漏洞，及时升级并回归测试。

结语

Multer 作为 Node.js 生态中最古老的文件上传中间件之一，其稳定性和社区活跃度一直较高。本次暴露的 req.files 与 req.file 行为不一致问题，虽不致命，却在关键时刻可能引发线上事故。开发者不应盲目信任中间件内部的自动目录创建能力，而应通过显式工程化手段，确保文件系统操作的健壮性。截至发稿时，Multer 维护者尚未正式回应此问题，我们也将持续跟踪后续修复进展。