1. 文件上传下载到底在解决什么问题

做Java Web开发的人，绕不开文件上传下载这块内容。不管你后面用的是Spring Boot还是什么花里胡哨的框架，底层那套东西还是Servlet规范里定义的那一套。我在实际项目里见过太多人，一上来就复制粘贴一段MultipartFile的代码，跑通了就完事，结果遇到大文件上传内存溢出、中文文件名乱码、下载时浏览器直接打开文件而不是弹出保存框这些问题时，完全不知道从哪下手排查。这篇内容就是想把Servlet层面文件上传下载的完整逻辑拆开讲清楚，从协议原理到代码实现到踩坑排查，一条线走完。

先说清楚这个主题适合谁看。如果你刚开始学Java Web，对request.getInputStream()和response.getOutputStream()还不太熟，那这篇能帮你把地基打牢；如果你已经用过框架的上传下载功能但没深究过底层，这篇能帮你补上那块缺失的拼图，以后遇到诡异问题不至于抓瞎。核心关键词就三个：Servlet文件上传、Servlet文件下载、multipart/form-data解析。这三个词贯穿全文，我会围绕它们把每个环节的操作细节和背后逻辑都摊开来讲。

文件上传下载这件事，表面上看就是“把文件传上去”和“把文件拿下来”，但实际涉及的东西比想象中多。上传这边要处理HTTP协议的multipart格式解析、文件大小限制、临时文件管理、文件名安全处理；下载这边要处理响应头设置、断点续传支持、大文件流式输出、内容类型识别。每一个点单独拎出来都够写一篇的，我尽量在一条主线里把它们串起来，该展开的地方展开，该给代码的地方给代码。

2. 上传功能的协议基础与核心设计思路

2.1 为什么上传必须用multipart/form-data

很多人知道上传表单要写enctype="multipart/form-data"，但未必想过为什么。普通表单默认的编码方式是application/x-www-form-urlencoded，它会把表单数据拼成key=value&key=value这样的字符串，然后对特殊字符做URL编码。这种格式处理纯文本没问题，但文件是二进制数据，里面可能包含任意字节序列，包括&和=这些分隔符，一旦混进去整个解析就乱了。而且URL编码会把二进制数据膨胀好几倍，效率极低。

multipart/form-data的思路完全不同。它把整个请求体切分成多个部分（part），每个部分用一段随机生成的边界字符串（boundary）隔开。每个part有自己的头部，里面写明这个部分的字段名和文件名，头部和内容之间空一行，然后是原始二进制内容。这样文件数据不需要做任何编码转换，原样传输，解析的时候按boundary切分就行。这个设计的关键在于boundary要足够随机，保证不会和文件内容里的字节序列撞车。浏览器一般会生成类似----WebKitFormBoundary7MA4YWxkTrZu0gW这样的字符串，碰撞概率极低。

理解了这个格式，你就能明白为什么Servlet 3.0之前处理上传那么痛苦——得自己读InputStream，自己找boundary，自己切分part，自己解析头部。Servlet 3.0之后规范里直接加了Part接口和getParts()方法，容器帮你把解析工作做完了，你只需要调request.getPart("fieldName")就能拿到文件。这是质的飞跃，也是我建议所有新项目直接用Servlet 3.0+的原因。

2.2 Servlet 3.0的Part接口与配置项

要用Servlet 3.0的上传支持，第一步是在web.xml里或者用注解开启multipart配置。web.xml的写法是在servlet标签里加multipart-config子元素，可以配四个参数：location指定临时文件存放目录，max-file-size限制单个文件大小，max-request-size限制整个请求大小，file-size-threshold指定超过多少字节才写入临时文件（小于这个值的直接放内存里）。如果用注解，就在Servlet类上加@MultipartConfig注解，参数名对应。

这里有个容易忽略的点：file-size-threshold设成0意味着所有上传文件都直接写磁盘临时文件，设成一个较大值则小文件走内存。我一般设成1MB左右，小文件走内存快，大文件落磁盘不撑爆堆。max-file-size和max-request-size的区别也要搞清楚，前者管单个part，后者管整个请求所有part加起来。曾经有个项目只设了max-file-size没设max-request-size，结果有人一次传十个文件，每个都没超限，但加起来把内存干爆了。这两个参数要配合着设，max-request-size一般设成max-file-size的几倍，留出余量。

临时文件目录location这个参数，如果不配，容器会用默认的临时目录（比如Tomcat的work目录下）。生产环境建议显式配一个独立的、有足够空间的目录，并且要注意这个目录的清理策略。Part对象有个delete()方法可以手动删临时文件，但如果你忘了调，临时文件会一直堆着。我见过一个线上服务跑了半年，临时目录攒了几十G的垃圾文件，就是因为代码里只处理了文件内容没调delete()。这个坑后面讲实操的时候会再强调。

2.3 文件名处理的三个关键动作

拿到Part之后，通过part.getSubmittedFileName()能拿到客户端传来的原始文件名。这个文件名绝对不能直接拿来用，必须做三件事。第一是防路径穿越，有人可能传一个文件名叫../../etc/passwd这样的，如果你直接拼到目标目录后面，文件就写到系统目录去了。处理办法是用FilenameUtils.getName()或者自己写逻辑只取最后一段，把路径分隔符都干掉。第二是处理中文乱码，不同浏览器和容器组合下，getSubmittedFileName()返回的中文名可能是乱码，需要在请求层面设置编码或者对文件名做转码处理。第三是重名问题，多个用户传同名文件会互相覆盖，常见做法是用UUID加原扩展名重新命名，或者用时间戳加随机数。

我个人的习惯是存储文件名用UUID，数据库里单独存一列原始文件名用于展示和下载时还原。这样既避免了重名覆盖，又避免了文件名里的特殊字符引发各种诡异问题。原始文件名在入库前也要做长度截断和特殊字符过滤，防止有人传个几百字符的文件名把数据库字段撑爆。这些细节看着琐碎，但都是实际踩过坑之后总结出来的。

3. 上传实操：从表单到落盘的完整链路

3.1 前端表单的最小可用写法

先给一个能跑的最小表单。关键就三个：method必须是post，enctype必须是multipart/form-data，文件输入框type="file"。少任何一个上传都会失败，而且失败得莫名其妙——method写成get的话文件内容根本不会进请求体，enctype不写的话服务端拿不到Part。我见过新手在这两个地方反复折腾的，所以这里特意点出来。

<form action="/upload" method="post" enctype="multipart/form-data"> <input type="file" name="file" /> <input type="submit" value="上传" /> </form>

如果要支持多文件，给input加multiple属性，服务端用request.getParts()遍历或者getPart的复数形式处理。注意name属性要和服务端getPart的参数一致，不一致的话拿到的Part是null，这个错误很隐蔽，因为不报异常只是拿不到数据。

3.2 服务端Servlet的完整处理代码

下面这段代码是我在实际项目里用的简化版，去掉了业务逻辑只保留上传核心。先看代码再逐段解释。

@WebServlet("/upload") @MultipartConfig( location = "/data/tmp", maxFileSize = 10 * 1024 * 1024, maxRequestSize = 50 * 1024 * 1024, fileSizeThreshold = 1024 * 1024 ) public class UploadServlet extends HttpServlet { private static final String SAVE_DIR = "/data/uploads"; @Override protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { request.setCharacterEncoding("UTF-8"); response.setContentType("text/html;charset=UTF-8"); try { Part part = request.getPart("file"); if (part == null || part.getSize() == 0) { response.getWriter().write("未选择文件"); return; } String originalName = part.getSubmittedFileName(); String safeName = sanitizeFileName(originalName); String ext = getExtension(safeName); String storedName = UUID.randomUUID().toString().replace("-", "") + ext; File saveDir = new File(SAVE_DIR); if (!saveDir.exists()) { saveDir.mkdirs(); } File target = new File(saveDir, storedName); try (InputStream in = part.getInputStream(); OutputStream out = new FileOutputStream(target)) { byte[] buffer = new byte[8192]; int len; while ((len = in.read(buffer)) != -1) { out.write(buffer, 0, len); } } part.delete(); response.getWriter().write("上传成功，存储名：" + storedName); } catch (IllegalStateException e) { response.getWriter().write("文件超过大小限制"); } } private String sanitizeFileName(String name) { if (name == null) return "unknown"; name = name.replace("\\", "/"); int idx = name.lastIndexOf('/'); if (idx >= 0) name = name.substring(idx + 1); name = name.replaceAll("[\\r\\n]", ""); if (name.length() > 200) name = name.substring(name.length() - 200); return name; } private String getExtension(String name) { int dot = name.lastIndexOf('.'); return dot >= 0 ? name.substring(dot) : ""; } }

这段代码里有几个设计决策值得说。缓冲区用8KB而不是1KB，是因为实测下来8KB在大多数磁盘和网络环境下吞吐更好，太小了系统调用次数多，太大了内存占用高收益不明显。用try-with-resources保证流一定关闭，这个不用多说。part.delete()放在文件写完之后调，清理临时文件。catch里捕获IllegalStateException是因为超过maxFileSize时容器会抛这个异常，不捕获的话用户看到的是500错误页，体验很差。

3.3 大小限制的异常处理与用户提示

大小限制这块要特别注意异常类型。超过max-file-size抛的是IllegalStateException，超过max-request-size抛的可能是IllegalStateException也可能是ServletException，取决于容器实现。稳妥的做法是两个都捕获，给用户一个明确的“文件太大”提示。另外前端最好也做一层大小校验，用JS读file.size，超过限制直接拦下来不发请求，省得浪费带宽。但前端校验只是体验优化，服务端校验绝对不能省，因为请求可以绕过前端直接发。

还有一个细节：如果上传过程中客户端断开连接，part.getInputStream()读的时候可能抛IOException，这时候已经写入的部分文件要清理掉，不然会留下半截文件。我的做法是在catch块里判断target文件是否存在，存在就删掉。这个逻辑在代码里没写出来是为了保持简洁，但实际项目里一定要加。

4. 下载功能的响应控制与流式输出

4.1 下载响应的三个关键头

文件下载的本质是把文件字节流写进response的输出流，但光写流不够，还得告诉浏览器这是个下载而不是页面内容。关键在三个响应头。Content-Disposition设成attachment; filename="xxx"告诉浏览器弹出保存对话框，filename指定默认文件名。Content-Type设成application/octet-stream表示二进制流，浏览器不会尝试解析。Content-Length设成文件字节数，浏览器能显示下载进度。这三个头缺一个体验就打折扣，缺Content-Disposition浏览器可能直接打开文件（比如图片、PDF），缺Content-Length进度条就不准。

文件名这里有个大坑：如果文件名含中文或空格，直接塞进Content-Disposition会出问题。标准做法是用URLEncoder对文件名编码，然后拼成filename*=UTF-8''编码后的名字这种RFC 5987格式。同时为了兼容老浏览器，再给一个filename=的普通版本（用ISO-8859-1编码）。两个都写，浏览器会优先用带星号的那个。这个处理不做的话，中文文件名下载下来要么乱码要么变成一串百分号。

4.2 流式输出的正确姿势

下载大文件时绝对不能把整个文件读进内存再写出去，必须边读边写。用FileInputStream配合8KB缓冲区循环读写，内存占用恒定。这里有个容易犯的错：在写流之前调用了response.getWriter()，一旦调了getWriter就不能再调getOutputStream()，两者互斥。下载场景必须用getOutputStream()，千万别在前面不小心写了getWriter()。

@WebServlet("/download") public class DownloadServlet extends HttpServlet { private static final String SAVE_DIR = "/data/uploads"; @Override protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { String storedName = request.getParameter("name"); if (storedName == null || storedName.contains("..") || storedName.contains("/")) { response.sendError(400, "非法参数"); return; } File file = new File(SAVE_DIR, storedName); if (!file.exists() || !file.isFile()) { response.sendError(404, "文件不存在"); return; } String downloadName = request.getParameter("origin"); if (downloadName == null || downloadName.isEmpty()) { downloadName = storedName; } String encoded = URLEncoder.encode(downloadName, "UTF-8").replace("+", "%20"); response.setContentType("application/octet-stream"); response.setHeader("Content-Disposition", "attachment; filename=\"" + encoded + "\"; filename*=UTF-8''" + encoded); response.setContentLengthLong(file.length()); try (InputStream in = new FileInputStream(file); OutputStream out = response.getOutputStream()) { byte[] buffer = new byte[8192]; int len; while ((len = in.read(buffer)) != -1) { out.write(buffer, 0, len); } out.flush(); } } }

参数校验那段很关键。storedName来自请求参数，如果不校验直接拼路径，攻击者传个../../就能读到系统任意文件。我用了contains("..")和contains("/")双重判断，虽然简单但有效。更严谨的做法是解析成File之后用getCanonicalPath()判断是否在允许目录下，这个后面排查部分会展开。

4.3 断点续传的简化实现思路

标准下载每次从头传，文件大了体验不好。断点续传的核心是Range请求头。客户端发请求时带Range: bytes=1024-，表示从1024字节开始要。服务端解析这个头，返回206状态码，设置Content-Range: bytes 1024-2047/2048表示返回的范围和总大小，然后从指定位置开始读文件写流。用RandomAccessFile的seek()方法定位到起始字节。这个功能不是必须的，但视频、大安装包这类场景很有用。实现的时候要注意Range格式的解析容错，格式不对就忽略Range返回完整文件，别报错。

5. 常见问题排查与避坑经验实录

5.1 上传下载高频问题速查表

下面这张表是我这些年遇到问题后整理的，基本覆盖了新手到中级开发者会碰到的绝大多数情况。

5.2 路径穿越与文件类型校验的实战处理

路径穿越这个问题，光靠字符串替换不够稳。我现在的做法是：目标目录先取getCanonicalPath()，拼接后的文件也取getCanonicalPath()，然后判断后者是否以前者开头。这样不管攻击者用什么编码技巧，只要最终解析出来的真实路径不在允许目录下就拒绝。代码大概是这样：

File baseDir = new File(SAVE_DIR).getCanonicalFile(); File target = new File(baseDir, storedName).getCanonicalFile(); if (!target.getPath().startsWith(baseDir.getPath() + File.separator)) { throw new SecurityException("路径非法"); }

文件类型校验方面，光看扩展名不可靠，因为扩展名可以随便改。更稳的做法是读文件头几个字节判断魔数（magic number），比如JPEG开头是FF D8 FF，PNG是89 50 4E 47。但魔数校验也有局限，不是所有格式都好判断。我的策略是白名单加魔数双重校验：只允许业务需要的几种扩展名，再对图片类做魔数校验。这样兼顾了安全和实现成本。

5.3 大文件上传的内存与超时调优

传几百MB甚至上GB的文件时，默认配置往往扛不住。除了前面说的fileSizeThreshold要设小让大文件落磁盘，还要注意连接超时和读取超时。Tomcat的connectionTimeout默认20秒，大文件上传很容易超，要在server.xml里调大。另外maxSwallowSize这个参数控制上传失败后容器吞掉剩余请求体的最大字节数，设太小的话客户端会收到连接重置而不是正常的错误响应。这些参数不在Servlet代码里，但在实际部署时绕不开，我一般会在项目文档里专门记一笔。

还有一个经验：大文件上传建议前端做分片，把文件切成几MB的块分别上传，服务端合并。这样单次请求小，超时和内存压力都小，还能支持断点续传。分片上传的实现比单次上传复杂不少，涉及分片序号、合并顺序、临时分片清理，如果业务确实有大文件需求，值得单独设计一套。

6. 从Servlet到框架：底层逻辑的迁移价值

很多人会问，现在都用框架了，还学Servlet这层干嘛。我的体会是，框架的上传下载功能再封装，底层还是这套东西。MultipartFile的getInputStream()背后就是Part的流，ResponseEntity的流式输出背后就是response.getOutputStream()。你理解了Part的临时文件机制，就能明白为什么框架里要配spring.servlet.multipart.location；你理解了Content-Disposition的编码规则，就能明白框架里下载文件名乱码该怎么调。底层清楚的人排查问题快，因为知道该看哪一层。

我在实际项目里遇到过一个案例：某服务下载中文名文件在某个浏览器上乱码，团队里用框架的人查了半天框架配置没找到原因，最后发现是框架版本对RFC 5987编码的处理有差异，手动在响应头里补了filename*才解决。这种问题不看底层根本定位不到。所以我的建议是，框架要用，但Servlet这层的基本功不能丢，尤其是文件上传下载这种和协议、容器、浏览器都打交道的功能，底层知识就是排查问题的底气。

最后分享一个小技巧：调试上传下载问题时，抓包工具比看代码管用。上传看请求体的Content-Type里boundary对不对、part结构完不完整；下载看响应头的Content-Disposition和Content-Length。很多问题抓一次包就水落石出了，比在代码里加一堆日志高效得多。这个习惯我从入行保持到现在，屡试不爽。