multipart请求文件名变更：Node.js用multer如何保留阿拉伯原文件名

安全阿岳

2026-11-5

问题根因

出现阿拉伯语文件名被错误转成类似E'DC这类乱码，核心是多环节的字符集解码错位：

Postman发送multipart/form-data请求时，阿拉伯语文件名是按UTF-8编码转为二进制流传输的
基于busboy的multer解析层默认按ISO-8859-1（Latin1）单字节编码解码文件名，完全无法识别多字节的UTF-8阿拉伯语字符
解码错位后生成的乱码字符串，就是接口实际接收到的错误文件名，整个过程不存在文件名的主动字符替换，纯粹是编码不匹配导致的解码错误

具体实现步骤

修正multer的文件名解码逻辑
这是最核心的解决手段，分两种适配场景覆盖不同版本的multer：
1. 如果使用的是multer v1.4.5-lts.1及以上版本，可直接在初始化配置中指定fileCharset: 'utf8'，从底层busboy解析阶段就强制用UTF-8解码文件名，替代默认的Latin1解码规则，从根源避免编码错位：
```
const multer = require('multer');
// 新版multer直接指定解析编码
const upload = multer({
  storage: multer.diskStorage({
    destination: (req, file, cb) => cb(null, '你实际的文件存储目录路径'),
    // 这种配置下file.originalname已经是正确的UTF-8阿拉伯语文件名，不需要额外转码
    filename: (req, file, cb) => cb(null, file.originalname)
  }),
  fileCharset: 'utf8' // 核心配置，强制文件名解析用UTF-8
})
```
1. 如果使用的是旧版multer（不支持fileCharset参数），可在文件名生成回调中，对错误解码的文件名做手动转码还原，不需要额外安装第三方依赖：
```
filename: (req, file, cb) => {
  // 核心转码：将被Latin1错误解码的字符串转回原始UTF-8二进制，再按正确编码解析
  const restoredName = Buffer.from(file.originalname, 'latin1').toString('utf8');
  cb(null, restoredName);
}
```
转码逻辑验证：原阿拉伯语文件名مالك被错误按Latin1解码后生成的乱码（比如示例中的E'DC），经过上述Buffer转换步骤，即可还原原始字符，彻底解决乱码问题。

增加兼容判断，避免破坏正常的英文文件名
纯转码逻辑会对所有上传文件生效，针对纯ASCII命名的文件可以加简单判断跳过转码，避免不必要的转换导致文件名异常：

filename: (req, file, cb) => {
  let targetName = file.originalname;
  // 判断原文件名是否存在被Latin1解码的特征：如果存在非ASCII字符，就触发转码还原
  if (/[^\u0000-\u007F]/.test(file.originalname)) {
    targetName = Buffer.from(file.originalname, 'latin1').toString('utf8');
  }
  cb(null, targetName);
}

排查链路中间层的编码干扰
如果调整完multer配置后依然有乱码，需要排查服务链路中的其他环节：
- 确认Node服务前面挂载的反向代理（比如Nginx）没有对multipart请求流做额外的字符集转换，不要强行将UTF-8流转为Latin1编码
- 检查Node入口层的表单解析中间件，不要在multer之前对multipart请求体做提前读取和编码转换
Postman侧的基础校验
排除服务端问题后，可验证Postman的上传配置：在form-data选项卡选择待上传文件后，确认输入的文件名是阿拉伯语原字符，没有被Postman自动转码为其他编码格式。

内容的提问来源于stack exchange，提问作者coder_0293