Layui上传文件提示“请求上传接口出现异常”的排查方法

作者：袖梨 2026-07-29

Layui.upload报“请求上传接口出现异常”根本原因是服务端响应格式不符：必须返回纯文本"0"或JSON中严格含code:0且无多余顶层字段；Content-Type须为application/json；跨域、非200状态码、空响应等也触发该提示。

为什么 `layui.upload` 一直提示“请求上传接口出现异常”

该错误并非前端代码自身崩溃，而是 layui.upload 服务端响应送达后，提示由主动判定“上传失败”而抛出。layui 对成功响应有硬性要求，只接受两种，其中一种是纯文本；因此根本原因几乎总是服务端返回的数据格式不合规 "0"，或者 json 中必须包含 code: 0 字段，且不能受到其他顶层字段干扰。

`dataFilter` 为何被忽略？检查是否误用 `done` 回调

Layui 的上传组件不走标准 Promise 或 success 钩子，它靠 done 回调处理服务端返回。但很多人把逻辑写在 done 里，却没注意：如果服务端返回的是 {"code":0,"msg":"ok","data":{"src":"xxx"}}，Layui 默认只取最外层的 code 和 msg，data 会被直接丢弃——除非你手动用 dataFilter 做转换。

未添加 dataFilter 时，Layui 规定响应体必须是 {"code":0,"msg":"success"} 或者 {"code":0}，即使只多出一个字段（例如 data），也可能被判断为解析失败
添加 dataFilter 以后，需要自行 return 一个满足 Layui 要求的对象：return {code: res.code, msg: res.msg || '上传成功'}
常见错误包括：在 dataFilter 里执行了 return 却返回了，或根本没有写 return res.data（错误！这是文件信息，并非上传结果对象）

Content-Type 并非后端返回的 `application/json` 时，同样会引发该错误

Layui 内部用 JSON.parse 尝试解析响应体，前提是它认为这是 JSON。如果后端返回 text/plain 或 text/html（比如 PHP 没设 header、Node.js 忘了 res.json()），哪怕内容是 {"code":0}，Layui 也会因类型不匹配而静默失败，最终显示“请求上传接口出现异常”。

PHP 示例：必须添加 header('Content-Type: application/json; charset=utf-8');
Node.js（Express）示例：用 res.json({code: 0})，不要使用 res.send(JSON.stringify({...}))
Java（Spring Boot）：确保 Controller 方法返回 @ResponseBody + 对象，或者显式设置 produces = "application/json"