Postman文件上传失败主因是form-data未严格遵循multipart协议：Key名须与后端@RequestParam参数名完全一致，File类型必须手动切换，所有字段（含文本和文件）须同在form-data表格内，且不可手填Content-Type。
form-data 不是“填表单”，而是构造 multipart 请求体；填错 Key 名或类型，90% 的上传会直接 400 或静默失败。
Key 名必须和后端 @RequestParam 或 @RequestPart 的参数名完全一致
后端接收字段名不是固定的 file，它由接口定义决定。比如 Spring Boot 控制器写的是：
@PostMapping("/upload")
public Result upload(@RequestPart("excelFile") MultipartFile file)
那你在 Postman 的 Key 栏就必须填 excelFile，不能填 file 或 upload。
- 抓包确认最可靠：用浏览器开发者工具 Network 面板看真实请求的 form-data 字段名
- 若后端用数组接收多文件（如
@RequestPart("files") List），Postman 要重复添加多个 Key 都叫files，每个设为 File 类型 - Key 名含下划线、驼峰、中横线时，大小写必须一字不差——
user_id≠userId
File 类型必须手动切换，Text 是默认值但会导致上传失败
Postman 的 form-data 表格里，每行 Key 右侧有个下拉菜单，默认是 Text。上传文件时，这个必须点开改成 File，否则你选的文件根本不会进请求体，后端收到的是空字符串或 null。
Postman 12.27.7
下载
Postman 12.27.7 Windows x64 官方安装包，适用于 API 设计、调试、测试与协作。该系列包含 Enterprise 云端性能测试静态 IP 出口能力，以及接口规范标签管理改进，适合受限网络测试与规范资源组织场景。
- 改完类型后，Value 列才会出现
Select Files按钮 - 单文件上传：点按钮选一个文件即可
- 多文件上传（同名）：选中多个文件（Ctrl/Cmd 多选），或重复添加相同 Key 名 + File 类型的行
- 误用 Text 类型传文件路径字符串（如
"./data/test.xlsx"）毫无意义，后端收不到二进制内容
普通参数和文件必须在同一个 form-data 表格里混填，不能拆到 Headers 或 x-www-form-urlencoded
multipart 请求要求所有字段（文本参数 + 文件）都封装在同一组 boundary 分隔块中。如果把 userId 放进 Headers、token 塞进 URL 参数、文件丢进 form-data，后端解析器大概率只看到文件，其他字段全丢失。
- 所有参数——包括
tenantId、type、overwrite这类开关——都得加在 form-data 表格里，Key 设为 Text 类型 - Content-Type 头部**不要手动填写**：Postman 切换 form-data 后会自动生成
multipart/form-data; boundary=----WebKitFormBoundary...，手填反而可能出错 - 登录态通常靠 Cookie：如果接口需要鉴权，优先用 Postman 的 Cookies 管理器自动带入，而不是把 sessionid 塞进 form-data
上传大 Excel 文件时要注意 timeout 和后端限制
Postman 默认超时是 0（无限制），但后端 Nginx、Spring、Tomcat 往往有默认限制，比如 10MB 文件大小、30 秒读取超时。上传 50MB 的 report.xlsx 极易卡在 pending 然后报 net::ERR_CONNECTION_TIMED_OUT。
- 先查后端配置：Nginx 的
client_max_body_size、Spring 的spring.servlet.multipart.max-file-size - Postman 自身不报错，但响应为空或 status 0 时，大概率是被网关拦截了
- 测试前用小文件（
最容易被忽略的是 Key 名匹配和类型切换——这两个动作看似简单，却是 form-data 上传失败最集中的地方。别信文档写的“file”字段名，一定要以抓包为准。
