凌晨一点多群里甩过来一张截图红字一行the request was rejected because no multipart boundary was found后面跟一句“文件传不上去接口挂了”。这个报错我这些年见过的次数不算少它有个很有意思的特点新手看了完全懵老手看了三秒钟就知道该往哪查。因为它不是在骂你代码写得烂而是在告诉你一件非常具体的事——你发过来的这个multipart/form-data请求头里没带 boundary 参数我没法把它切开所以我拒收。这篇东西就是围绕这一个报错展开的。我会说清楚它到底由谁抛出、boundary 在协议里扮演什么角色、为什么它会被“弄丢”、前端各语言客户端和后端各框架分别该怎么写才算正确以及一套我自己常用的五步排查法。适合的对象很宽刚接手文件上传功能的新人、被网关坑过一次的中级开发、以及需要排查线上偶发上传失败但日志里只有一行异常的老手。代码示例以 JavaScript、Java、Python、命令行工具为主但思路是通用的换成任何语言都能套。1. 先搞清楚这个报错是谁抛出来的1.1 这句英文的出处比你想象的集中很多人第一反应是“浏览器报的”或者“网络问题”其实都不是。这句话的原文是the request was rejected because no multipart boundary was found它是服务端解析器抛出来的最早出现在一套被广泛使用的文件上传解析组件里核心逻辑大致是这样String contentType req.getContentType(); if (contentType ! null contentType.toLowerCase(Locale.ENGLISH).startsWith(multipart/)) { boundary getBoundary(contentType); if (boundary null) { throw new FileUploadException( the request was rejected because no multipart boundary was found); } }这段代码有几个细节值得盯住。第一只有当 Content-Type 以multipart/开头时才会走进这个分支也就是说报这个错说明请求头里确实写了multipart/form-data只是后面没跟; boundaryxxx。如果 Content-Type 压根不是 multipart比如被写成了application/json或者干脆是空的那走的是另一条分支报的会是“content type was not a multipart/form-data”这类信息症状完全不同。这个区分很重要它直接决定了你往哪个方向查。第二不同容器版本的异常包装层数不一样。运行在内嵌容器里的应用最终在日志里看到的往往是长长一串类似MultipartException: Failed to parse multipart servlet request; nested exception is java.io.IOException: ...FileUploadException: the request was rejected because no multipart boundary was found。别被外层那个通用异常吓住真正有用的信息永远在最后面那句。很多人看到MultipartException就去翻自己的 Controller 代码翻了半小时才发现问题根本不在业务层。我个人的习惯是看到这个错先把“前端代码”这四个字在心里划掉一半因为八成的案例里前端确实是错的而且错得非常统一。1.2 从客户端到容器boundary 可能在五个地方消失一个上传请求从用户点“提交”到后端拿到文件中间要过好几道关。每一道关理论上都有可能动这个请求头我把常见的链路和对应的嫌疑点列一下链路环节会不会动 Content-Type典型症状排查手段前端业务代码极高频头里只有multipart/form-data没有 boundary浏览器开发者工具看 Request Headers请求库/拦截器高频全局注入了错误的默认类型在拦截器里打日志客户端本地抓包代理低频少数工具会重写头关掉代理直连试一次网关/反向代理中低频内网直连通、走网关不通curl 分别打两个地址对比应用容器/框架解析器低频版本行为差异、配置错误看完整异常栈、查配置项这里有个非常关键的分界线看请求头里有没有 boundary就能把问题一刀切成两半。有 boundary 说明前端是干净的问题在中间层或者后端没有 boundary 说明压根轮不到后端说话前端自己就把头写坏了。我遇到过最离谱的一次是某业务线的前端在封装请求方法时写死了Content-Type: multipart/form-data所有上传接口全军覆没但因为他们本地用的测试工具会自动补全这个头所以一直没发现。我建议每个接手上传功能的人都先在心里建立这样一个模型boundary 是客户端生成的、服务端消费的它诞生于客户端把 FormData 序列化成字节流的那一刻一旦这一步被干扰后面全是白搭。2. 把 multipart 报文拆开看boundary 是那个“隔板编号”2.1 一份完整的上传报文长什么样要真正理解这个报错得看一眼原始报文。很多人用了几年上传功能却从没见过multipart/form-data的裸报文长啥样这是很可惜的。它其实非常朴素POST /api/upload HTTP/1.1 Host: upload.internal Content-Type: multipart/form-data; boundary----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Length: 342 ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; namefile; filenamereport.pdf Content-Type: application/pdf 这里是文件的二进制字节 ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; namebizType invoice ------WebKitFormBoundary7MA4YWxkTrZu0gW--看明白这份报文这个报错就懂了一大半。boundary 这个字符串在报文里出现了两个角色一是在请求头里声明一次告诉服务端“我用这个字符串当分隔符”二是在请求体里作为每一段的起始标记形式是--加上 boundary。最后一段结束后还要再来一次--加上 boundary 再加上--表示全部结束。我一般用打包打比方你要往一个大箱子里装好几件东西每件东西前面插一块隔板隔板编号统一。收件方拆箱之前先看一眼清单也就是 Content-Type知道隔板编号是啥才能按编号把箱子切成一段一段。如果清单上写着“这是分隔装运的”但没写编号那仓库管理员除了拒收没别的选择——这就是那个报错的全部含义。有个细节经常被忽略boundary参数和前面的分号之间通常有个空格写成multipart/form-data; boundaryxxx。绝大多数解析器对空格是宽容的但个别老实现比较挑剔。如果你是手工拼报文建议老老实实按标准格式来别省这个空格。2.2 为什么 boundary 必须由程序生成不能写死有人会想那我干脆固定用boundaryabc123不就永远不会丢了吗这个想法非常危险原因有两个。第一个是碰撞问题。boundary 的职责是分隔各段内容一旦它出现在某一段的正文里解析器就会把它误判成分隔符导致这段内容被提前截断。你上传的文件是二进制里面出现任意字符串的概率并不低。所以规范要求 boundary 足够长、足够随机浏览器生成的通常有三十多个字符就这么来的。你写个abc123等于给自己埋雷——平时没事某天用户传了个恰好包含这串字节的压缩包文件就悄悄损坏了而且不会有任何报错这种 bug 查起来能让人崩溃。第二个是规范约束。boundary 允许使用的字符是有限制的长度也不建议超过 70 个字符。不同实现对超长 boundary 或者包含特殊字符的 boundary 处理不一致有的截断、有的直接报错。所以正确的做法只有一个让库去生成你不要碰它。这一条是整个话题的核心后面讲的所有坑本质都是“有人手贱碰了它”。3. 前端侧六个高频踩坑点与正确写法3.1 手动写 Content-Type 是头号元凶我统计过自己经手过的案例这个错的占比超过七成。典型代码长这样const formData new FormData(); formData.append(file, file); axios.post(/api/upload, formData, { headers: { Content-Type: multipart/form-data } // 罪魁祸首 });看起来人畜无害甚至很“规范”实际上它把浏览器的自动行为给掐断了。原理是这样的当你调用XMLHttpRequest.send(formData)时如果开发者没有手动设置过 Content-Type浏览器会自己接管这件事生成一个随机的 boundary拼成multipart/form-data; boundary----WebKitFormBoundaryXXXX发出去。但只要你调过一次setRequestHeader(Content-Type, ...)浏览器就认为“你已经自己搞定了”不再插手你写什么它就发什么。于是结果就是请求头被原样发成multipart/form-data没有 boundary服务端解析器当场拒收。而本地测试之所以经常发现不了是因为很多接口调试工具在识别到 FormData 后会自己补上 boundary把问题掩盖掉。正确的写法就是不写axios.post(/api/upload, formData);用原生fetch同理fetch(/api/upload, { method: POST, body: formData // 千万不要在这里加 headers: { Content-Type: multipart/form-data } });注意如果你确实需要加别的头比如鉴权 token那没问题单独特么加那个头就行只是别碰 Content-Type。有些同学图省事写成headers: { ...defaultHeaders, Content-Type: multipart/form-data }一个展开运算符就把自己送走了。还有个小坑值得一提某些请求库版本里即便你写了multipart/form-data库内部会检测到 data 是 FormData 然后主动帮你删掉这个头但另一些版本不会。这种“版本相关”的行为最坑人因为升级一次依赖同样的代码可能从能用到不能用或者反过来。所以别赌永远别写。3.2 拦截器统一设置请求头是更隐蔽的同类问题比手动写更隐蔽的是全局拦截器。很多项目都会在请求封装里做统一处理service.interceptors.request.use(config { config.headers[Content-Type] application/json; config.headers[Authorization] getToken(); return config; });平时接口全是 JSON这么写没毛病直到某天有人加了个上传接口。这个application/json会被带上去覆盖掉浏览器的自动行为在一些 XHR 实现里只要 Content-Type 被显式设置FormData 的自动处理就失效。而报错信息这次可能不是“no boundary”而是“content type was not a multipart/form-data”症状变了但根子一样。修法有两种我倾向于第一种service.interceptors.request.use(config { const isFormData config.data instanceof FormData; if (!isFormData) { config.headers[Content-Type] application/json; } return config; });另一种是在上传接口上显式覆盖Content-Type: undefined但我见过几个库对undefined的处理不一致有的会保留旧值所以不如在拦截器源头判断来得稳。提示拦截器里加一句console.log(config.headers[Content-Type])花不了几秒钟能省掉一下午。排查上传问题时我第一件事就是打开控制台看这个头的最终值。3.3 各语言客户端的正确姿势对照不同技术栈的写法差异挺大我整理成表格方便对照抄客户端错误写法正确写法说明axios浏览器手动设multipart/form-data不设直接传 FormData让浏览器生成 boundaryfetchheaders 里写死类型只传 body同上Android OkHttpaddHeader(Content-Type,multipart/form-data)用MultipartBody.Builder().setType(MultipartBody.FORM)手写头会覆盖构建器生成的带 boundary 的版本Python requestsheaders{Content-Type:multipart/form-data}配datafiles{file: open(...)}files 参数会自动生成 boundary命令行 curl-H Content-Type: multipart/form-data -d body-F filea.pdf-F 会自动处理小程序用 request 传 FormData用wx.uploadFile小程序没有 FormDatauploadFile 自带处理重点说下 OkHttp因为 Java 端这个问题特别多。MultipartBody.Builder在build()的时候会生成一个带 boundary 的 Content-Type 放到请求里。但如果你的代码里又手动addHeader(Content-Type, multipart/form-data)最终请求里会出现两个同名头或者后者覆盖前者服务端拿到的就是残缺的那个。我见过有人为了解决“重复头”问题又加了个拦截器去删头越修越乱。Python 的requests也有类似陷阱。data参数和files参数走的是完全不同的构造路径files会自动调urllib3的编码器生成 boundary而用data加手写头就什么都不会发生。这个区别在新人代码里非常常见。4. 后端与中间件解析器、网关、转发层4.1 Spring 两套解析器的差异与配置检查虽然这个错大概率是客户端造成的但后端侧也有几件事需要确认否则你会一直在错误的方向上打转。Java 生态里主流的 multipart 解析有两条路一条是基于 Servlet 3.0 规范的容器内置解析器需要配置spring.servlet.multipart.enabledtrue默认就是 true以及max-file-size、max-request-size、file-size-threshold几个参数另一条是老式的基于外部组件的解析器需要声明一个解析器 Bean。两条路最终都会在“找不到 boundary”时抛出这句异常只是包装层不同。配置上最容易出问题的是关掉或重复配置。比如有人为了排查别的问题临时把 multipart 关了忘了改回来或者同时存在两套解析器 Bean导致行为不可预期。我建议排查时直接看启动日志里有没有 multipart 相关配置的打印或者在 Controller 里临时打一行PostMapping(/upload) public String upload(RequestParam(file) MultipartFile file, HttpServletRequest request) { log.info(contentType {}, request.getContentType()); log.info(file {}, size {}, file.getOriginalFilename(), file.getSize()); return ok; }如果这行日志压根没打出来说明请求在进 Controller 之前就被解析器拦下了那问题必然在报文本身。如果打出来了但contentType是multipart/form-data不带 boundary那基本就锁定了。顺便提一个容易混淆的报错Required request part file is not present。这个是 boundary 没问题、报文也解析成功了但字段名对不上——前端 append 的时候写的是uploadFile后端RequestParam写的是file。这两个错的排查方向完全不同别搞混。4.2 网关和反向代理会不会动这个头会但概率不高属于“排除了前面所有可能之后才考虑”的层级。不过有些场景值得单独警惕。第一种是企业内部自建的网关做了请求头规整。有些网关为了统一格式会对 Content-Type 做解析再重组重组的时候只保留了主类型把参数丢了。这种情况的典型特征是内网直连后端完全正常走网关就必现。第二种是反向代理配置里出现了清空或覆盖头的指令。虽然默认配置不会动 Content-Type但项目里手写的配置文件千奇百怪出现proxy_set_header Content-Type 这种写法也不是没可能。第三种是某些安全防护组件对上传请求做预处理处理过程中重建了请求对象但没把参数带全。排查方法特别简单用命令行工具分别打两个地址对比返回# 直连后端 curl -v -F file/tmp/test.pdf http://127.0.0.1:8080/api/upload # 经过网关 curl -v -F file/tmp/test.pdf http://gateway.internal/api/upload-v会打印出实际发出的请求头你能清楚看到 boundary 有没有被带上。如果直连通、走网关不通再去看网关日志里记录的请求头对比一下就水落石出了。注意测网关的时候别用浏览器用命令行。浏览器那一套自动补全机制会干扰判断命令行工具的-F参数行为更透明。另外补充个容易被误认的坑上传大文件时报 413 而不是这个 boundary 错误那是请求体大小限制改client_max_body_size或者框架的max-request-size就行跟本文说的事没关系。新人容易把两者混为一谈。4.3 BFF 转发场景最容易二次踩坑的地方现在很多项目有中间层前端把文件传给中间层中间层再转发给真正的文件服务。这个架构下boundary 会被“消费两次”第二次比第一次更容易出错。典型错误是中间层把收到的文件读进内存然后又当成普通 JSON 字段转发// 错误示范 app.post(/api/upload, async (req, res) { const fileBuffer await readFile(req.files.file.path); await axios.post(http://file-service/upload, { fileName: req.files.file.name, content: fileBuffer.toString(base64) }); });这么写不算错但下游接到的就不是 multipart 请求了而是 JSON。如果下游接口只接受 multipart就会报各种各样的错。更隐蔽的是有些人重新构造 FormData 转发但在 axios 配置里又手写了 Content-Type导致同样的错误在中间层复现一遍。正确的转发姿势有两种。第一种是用流透传把收到的请求体直接 pipe 给下游这种方式最干净但要注意下游的鉴权头得单独处理。第二种是重新构造 FormData此时务必保持和前端一样的原则不手写 Content-Typeconst FormData require(form-data); const form new FormData(); form.append(file, fs.createReadStream(localPath)); await axios.post(http://file-service/upload, form, { headers: form.getHeaders() // 关键让 form-data 自己生成带 boundary 的头 });form.getHeaders()返回的就是带 boundary 的正确头这是 Node 环境下最稳的写法。如果你手动拼{Content-Type: multipart/form-data}同样的报错会在中间层原地复活。5. 我常用的五步排查法附命令5.1 前三步看头、绕过中间件、做对比这套流程我用了很多年绝大多数上传问题能在十分钟内定位。第一步看真实请求头。浏览器打开开发者工具切到网络面板找到那个上传请求看 Request Headers 里的 Content-Type。这一步是分水岭。如果值是multipart/form-data孤零零一个、后面没有; boundary别往下查了直接去改前端代码问题百分百在那里。如果带着一长串 boundary说明客户端是干净的继续往下。这一步有个细节有些工具里请求头是折叠显示的你得点开看完整值。我就见过有人看一眼觉得“有 multipart/form-data 啊”就跳过了实际上后面半截根本没显示出来。第二步绕过所有中间件直连后端。在后端机器上起个 curlcurl -v -F file/tmp/test.pdf -F bizTypeinvoice http://127.0.0.1:8080/api/upload如果这条命令通了说明后端和报文格式都没问题锅在中间层或者前端。如果不通那问题就在后端去看后端日志里完整的异常栈重点看是哪个解析器抛的。第三步逐层加回中间件。从直连后端开始一层一层往外加先打本机反向代理再打内网网关最后打对外域名。哪一层开始失败问题就在那一层的配置里。这个方法看着笨但比瞎猜高效得多尤其是多层架构的项目。心得我曾经排查一个偶发失败的问题白天怎么测都通晚上必现。后来用这个方法发现是两个网关实例的配置不一致负载均衡随机打过去一半正常一半报错。如果是凭经验猜猜到天黑也猜不出来。5.2 后两步抓包与日志打点前几步搞不定的时候就得上更硬的手段了。抓包。在服务端机器上抓一下真实流量确认报文到底长啥样tcpdump -i any -A -s 0 tcp port 8080 | grep -i -A3 POST /api/upload这条命令会把经过 8080 端口的明文请求打出来你能直接看到请求行和请求头。如果请求走了加密通道那就在客户端侧抓或者干脆在代码里打印。抓包的价值在于它不会骗人——你代码里写的、框架帮你改的、中间件帮你转的最终发到网线上的东西才是真相。日志打点。在后端入口处临时加几行日志把request.getContentType()、request.getContentLength()、请求方法、User-Agent 全打出来。有时候你会看到很有意思的东西比如某个特定版本的客户端 UA 才出问题那范围一下就缩小了。这两步做完还找不到原因的情况我印象里只遇到过一次最后发现是某台机器的时钟偏差导致请求被中间层判定为异常然后重建了请求对象。属于极端个例一般用不上。5.3 手工拼报文的自检清单有一类场景绕不开手工构造 multipart 报文嵌入式设备、老旧客户端、某些特殊协议对接。这时候没有库帮你生成 boundary只能自己来。我整理了一份自检清单按顺序过一遍基本不会错boundary 用足够长的随机串别用固定值长度控制在 20 到 60 字符之间。请求头写成Content-Type: multipart/form-data; boundary你的串注意分号后有个空格。每一段的起始是--加上 boundary紧接着必须是\r\n不能只写\n。每个段的头部和内容之间要空一行也就是连续两个\r\n。全部段结束后写--加上 boundary 再加上--作为结束标记。计算并填上准确的 Content-Length字节数算错会导致请求被截断。如果内容里有中文或二进制记住 Content-Length 算的是字节数不是字符数。最常见的两个错误一是忘了最后一行的结束标记服务端读到流末尾发现没结束行为不可预期二是行尾用了\n而不是\r\n部分严格的解析器会把它当成内容的一部分。这两点在自研协议对接里特别高频。6. 常见问题速查表与几条压箱底的经验6.1 上传相关问题速查表我把和上传相关、但报错信息长得很像的几类问题整理成表出问题时对着看一眼能少走弯路报错或现象真实原因处理方向no multipart boundary was foundContent-Type 是 multipart/form-data 但缺 boundary 参数客户端不要手写 Content-Typecontent type was not a multipart/form-dataContent-Type 完全不是 multipart被拦截器改成了 JSON拦截器排除 FormDataRequired request part xxx is not present报文解析成功但字段名对不上统一前端 append 名和后端参数名Current request is not a multipart request接口要求 multipart实际发的是 JSON检查请求体构造方式413 Request Entity Too Large请求体超限调整网关和框架的大小限制上传成功但文件大小为 0字段 append 时值为空或流已关闭检查 append 时机和读取方式中文文件名变乱码filename 参数编码问题指定 UTF-8 或做解码兼容连接被重置而不是返回 500服务端解析失败后未吞掉剩余请求体超限断连调整容器的 maxSwallowSize最后一条值得展开说。容器在解析失败之后需要把请求体剩余部分读掉才能正常返回响应但这个过程有大小上限默认通常是 2MB 左右。如果用户传的是 20MB 的文件解析在开头就失败了剩下的 20MB 超过上限容器干脆断开连接。于是前端看到的不是“no boundary”的报错而是“连接被重置”。这就是为什么同一个 bug小文件报明确错误、大文件却只显示网络异常——其实是同一个根因。知道这一点排查时就能把两类看似无关的现象串起来。6.2 文档里不会写的几条经验第一条永远不要相信“工具里能传就代表代码没问题”。接口调试工具、浏览器插件、甚至某些测试框架在识别到上传场景时会自动补全请求头。我接手过一个项目前端说“我用工具测过了能传”结果一看工具自动生成了 boundary而实际代码里写死了 Content-Type。判断前端对不对唯一标准是看浏览器网络面板里实际发出的头。第二条把“Content-Type 是全局设置的”这件事当成一个技术债记下来。只要项目里有全局拦截器统一设 JSON 类型就一定会有后来的人在加文件上传时踩坑。比较稳妥的做法是在封装层就区分好文件上传的通道而不是让每个业务方自己去绕。这个改动不大但能救后面好几个人的下午。第三条本地通线上不通大概率不是代码问题。遇到这种差异优先怀疑三件事网关配置不一致、两套环境依赖版本不一致、客户端版本不一致。我见过几次是因为线上用的是一个更旧版本的请求库对 FormData 的处理逻辑不同。第四条别急着在服务端加兼容代码。有些人看到这个报错第一反应是在后端写个拦截器检测到缺 boundary 就自己补一个。这个思路非常危险因为你补的 boundary 必须和请求体里的分隔符完全一致才行而请求体里压根就没用过任何 boundary——它的分隔符可能压根不存在也可能是某个别的字符串。硬补的结果是解析出乱七八糟的内容比直接报错更难查。最后分享一个我自己的习惯。凡是涉及文件上传的接口我都会在联调阶段先用命令行跑一次curl -v -F file/tmp/sample.bin http://host/api/upload把返回和请求头截图存到文档里作为这个接口的“基线”。以后谁再报上传问题先拿这条命令跑一遍通说明是客户端的问题不通说明是服务端或环境的问题两句话就能把范围砍掉一半。这个小动作花不了两分钟但在多人协作的项目里它省下来的沟通成本相当可观。上传功能看着简单其实是整个请求链路里少有的“协议细节直接暴露给业务代码”的地方boundary 只是其中最典型的一个。把这份报错吃透之后你会发现再遇到类似的协议层问题排查思路是通用的先确认报文长什么样再确认是谁改的最后才去改代码。
