Insomnia测试注册图片上传遇MulterError: Unexpected field排查求助

高优先级排查项（90%的问题出在这里） #

• 核对Insomnia实际请求的原始字段名：不要只看输入框的填写值，切到Insomnia请求的「Preview」标签，找到multipart/form-data的文件块，确认实际的name属性没有前后空格、大小写错误（比如误写成Image、image ）。同时确认文件字段是添加在「Form Data」tab下，没有额外添加非image名的文件字段（哪怕是空字段也会触发报错）。
• 检查是否存在全局multer中间件：如果在项目入口/路由挂载层已经全局引入过upload.any()/upload.single()类的中间件，请求会先被全局中间件读取文件流，到局部路由的字段匹配时就会失效。直接全局检索multer、upload.use这类关键词，确认没有全局挂载的上传中间件。
• 临时放宽字段限制测试：把路由里的upload.single("image")临时改成upload.any()，如果报错消失，直接打印req.files的字段名，和预期值对比，就能立刻定位字段名不匹配的具体原因。

你代码中存在的显性bug（会引发连锁问题） #

// 错误：req.file.filename是字符串，不能解构为对象
let { image } = req.file.filename
// 正确写法
const imageFilename = req.file.filename

// 错误：已使用diskStorage的情况下，multer配置里的destination参数无效
const upload = multer({ storage: storage, fileFilter: fileFilter, destination: './client/public/img' })
// 删掉多余的destination即可
const upload = multer({ storage: storage, fileFilter: fileFilter })

另外注意：upload.single("image")仅允许请求中存在1个名为image的文件字段，多传任何其他文件字段都会触发报错。 #

低概率排查项 #

• 检查multer版本：旧版（<1.4.4）存在字段名匹配的已知bug，升级到最新稳定版可解决
• 确认本地反向代理（比如Vite/Webpack Dev Server的proxy、Nginx）没有篡改请求的表单字段
• 确认请求的Content-Type是自动生成的multipart/form-data，没有手动修改边界值
• 确认没有引入其他会解析multipart/form-data的中间件，多个解析流互相干扰也会导致字段匹配失效

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