简介面向Java Web开发者的图片上传下载实战资料基于Spring Boot框架并与ckeditor4富文本编辑器集成覆盖文件存储、MultipartFile处理、接口安全、跨域设置等核心环节适合需要在内容管理系统或社交平台中快速实现图片功能的开发者。压缩包共71个文件大小133KB以35个Java源文件为主体搭配18个class文件、7个xml与6个yml配置文件、3个properties配置及1个jar包Maven工程结构完整便于直接导入IDE阅读。已有235人学习下载。其中包含pom.xml依赖管理、多环境yml配置、上传接口示例、文件名重命名与路径防遍历策略、异常处理与文件类型校验、ckeditor4所需的JSON响应结构及CORS配置并附带静态资源映射与安全下载思路可帮助开发者少走弯路快速落地一个可运行的图片上传下载模块同时也为云存储接入与图片处理等扩展方向提供了参考。1. Java 图片上传与下载为什么有人半天写完有人一周还在改Java 图片上传与下载经常被当成后端开发里最没技术含量的功能一个接口接收文件一个接口返回字节流半天就能写完。但真正到了上线前夜才会发现这功能和数据库一样是个黑匣子——图片打不开、中文文件名乱码、服务器重启后目录找不到、有人利用下载参数读取服务器文件任何一个都够加班到凌晨。这篇文章按一线项目里最常用的落地方式把整条链路拆开讲multipart 表单如何传到服务端、Servlet 原生 Part 接口怎么接、落盘该用什么目录结构和命名规则、下载响应头怎么设置再给出必踩的坑和验证手段。适合正在写管理后台、商城系统或内容平台的 Java 开发者也适合被面试题目录里“文件上传漏洞”绕晕、想一次补齐这块基础的同学。这套逻辑不依赖 Spring Boot 也能跑通。很多教程只贴三行注解看起来简单但换一个容器、换一个操作系统就失效。先理解协议层发生了什么再谈框架封装才是少走弯路的关键。2. 拆透上传下载链路multipart、Part 接口与两个关键响应头2.1 上传链路四要素enctype、表单体、Part 与存储位置图片上传本质是浏览器把二进制文件塞进 HTTP 请求体服务器再从请求体里把字节流抠出来写进磁盘。这里的第一步是表单的enctype属性。普通表单默认是application/x-www-form-urlencoded它会把所有字段做 URL 编码适合短文本但塞进大文件会低效且容易截断。上传文件必须显式声明为multipart/form-data浏览器才会按二进制方式传输并在请求里自动生成一个随机字符串作为 boundary 分隔线。请求体到达服务器后Servlet 容器会按 boundary 把内容切分成一段段。每段头部自带Content-Disposition: form-data; namefile; filenamexxx.jpg这就是我们常说的 Part 区域。Servlet 3.0 之后容器提供了原生Part接口直接把一段二进制流交给你处理不需要再引入 Commons FileUpload 这类第三方库。part.getInputStream()拿到字节流part.getSubmittedFileName()拿到原始文件名——这个方法从 Servlet 3.1 开始才有老项目里如果拿不到就得手动从part.getHeader(content-disposition)里解析 filename这一点兼容性很容易被忽略。参数层面需要理解三个值maxFileSize限制单个 Part 的大小maxRequestSize限制整个请求体的大小fileSizeThreshold表示文件超过多大时容器先将它写入临时文件而非全部留在内存。内存和磁盘是两种成本阈值设太小大图上传时频繁落盘导致变慢设太大并发一高就把堆撑爆。常见做法是单文件限制 5MB、整个请求限制 10MB阈值 1MB 左右。2.2 最小可跑实现一个 Servlet 覆盖上传与下载我一般把上传和下载写进一个WebServlet(/file/*)的类里通过getPathInfo()区分动作。这类实现不依赖 Spring MVC 也能直接丢进 Tomcat 跑代码全量贴出来package com.example.demo; import javax.servlet.ServletException; import javax.servlet.annotation.MultipartConfig; import javax.servlet.annotation.WebServlet; import javax.servlet.http.*; import java.io.*; import java.nio.file.*; import java.text.SimpleDateFormat; import java.util.Date; import java.util.UUID; WebServlet(/file/*) MultipartConfig( maxFileSize 5 * 1024 * 1024, // 单张图片最大 5MB maxRequestSize 12 * 1024 * 1024, // 整个请求最大 12MB fileSizeThreshold 1024 * 1024 // 超过 1MB 落临时磁盘 ) public class ImageFileServlet extends HttpServlet { private static final Path BASE_DIR Paths.get( System.getProperty(user.dir), upload); Override protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { if (!/upload.equals(req.getPathInfo())) { resp.setStatus(404); return; } Part part req.getPart(file); String originalName part.getSubmittedFileName(); // 1. 后缀白名单校验只收常见图片格式 String ext ; if (originalName ! null originalName.contains(.)) { ext originalName.substring(originalName.lastIndexOf(.)).toLowerCase(); } if (!ext.matches(\\.(jpg|jpeg|png|gif|webp))) { resp.setStatus(400); resp.getWriter().write({\message\:\only image allowed\}); return; } // 2. 按日期分目录避免单目录文件数量过大 String dateDir new SimpleDateFormat(yyyyMMdd).format(new Date()); Path dir BASE_DIR.resolve(dateDir); Files.createDirectories(dir); // 3. UUID 重命名不保留原文件名防止路径穿越和文件枚举 String storedName UUID.randomUUID().toString().replace(-, ) ext; Path target dir.resolve(storedName); // 4. 原图落盘try-with-resources 自动关闭流 try (InputStream in part.getInputStream()) { Files.copy(in, target, StandardCopyOption.REPLACE_EXISTING); } // 5. 返回相对 URL数据库里也只存这一串 resp.setContentType(application/json;charsetUTF-8); resp.getWriter().write({\url\:\/file/download?name dateDir / storedName \}); } }这段代码里有三个设计点值得细说。第一后缀校验用的matches(\\.(jpg|jpeg|png|gif|webp))只认白名单黑名单的做法比如单独禁掉 exe、jsp迟早会被绕过因为可执行文件的扩展名太多了。第二UUID 去掉横线后存为字符串加上日期目录等于把“业务可读性”全部丢给数据库表磁盘上只留一个无序的名字攻击者即使拿到下载地址也没法遍历整个目录。第三返回的 URL 是相对路径而不是http://ip:port/...的绝对路径这样以后换域名、换端口、做 CDN 都不用回头改表数据。下载逻辑放在 doGet 里同样写全Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { if (!/download.equals(req.getPathInfo())) { resp.setStatus(404); return; } String name req.getParameter(name); // 用 normalize startsWith 拦住 ../ 和绝对路径穿越 Path base BASE_DIR.toAbsolutePath().normalize(); Path file base.resolve(name).normalize(); if (!file.startsWith(base)) { resp.setStatus(400); return; } if (!Files.isRegularFile(file)) { resp.setStatus(404); return; } // 关键响应头告诉浏览器是下载而不是直接渲染 resp.setHeader(Content-Disposition, attachment; filename\ file.getFileName() \); String contentType Files.probeContentType(file); resp.setContentType(contentType ! null ? contentType : application/octet-stream); resp.setContentLengthLong(Files.size(file)); try (InputStream in Files.newInputStream(file); OutputStream out resp.getOutputStream()) { in.transferTo(out); } }下载链路里两个响应头决定了行为差异。Content-Type告诉浏览器这是什么类型Content-Disposition: attachment告诉浏览器“不要试图打开直接保存”。如果去掉 attachment改成inline浏览器就会把图片直接渲染在页面里——这通常是“预览”需求该做的事。代码里的路径校验用了normalize()加startsWith()的组合name参数传../时会被 normalize 解析后露出真实位置再和 base 目录比较就能识破。数据库里只存20240812/uuid.jpg这种相对路径到这一步拿出来 resolve 即可不会存在 Windows 反斜杠与 Linux 斜杠打架的问题。3. 把存储与命名做扎实UUID、日期分目录与中文文件名编码3.1 存储策略日期分目录与 UUID 命名什么场景例外上传落盘第一个决策点是目录结构。单目录存所有文件是最省事的写法但一旦超过几千个文件文件系统查找和备份都会变慢管理后台里按时间筛选也麻烦。常见做法是日期 / UUID.ext两级结构比如upload/20240812/9f2c1a3b.jpg。日期目录天然做了冷热分层后续做定时清理可以按目录直接删UUID 则把文件名和原始名彻底解耦避免用户上传../../etc/passwd这类带路径信息的名字被直接拼进存储路径。什么场景不要用 UUID用户头像、证件照这类“一人只保留一张”的业务更适合以用户 ID 或业务主键做目录名比如avatar/10001.jpg。这样做的好处是回读路径不用查库坏处是攻击者可以通过遍历 ID 下载所有用户头像——如果业务允许这么做就没事不允许则需要加鉴权。另外原始文件名在很多合规场景里必须保留比如合同扫描件、发票那就别把原始名塞进存储路径而是单独存一列original_name下载时再取出来拼进响应头。存储策略可读性安全性冲突概率适用场景日期 UUID差需查库高难枚举极低通用图片上传业务主键目录中可直读中可遍历低头像、用户证件原始文件名好低含路径信息高仅限内部工具使用这里还有一层安全校验容易被忽略只检查 Content-Type 不够。图片的 Content-Type 是客户端随请求头带过来的用浏览器上传时不可信可以用脚本伪造。真正判断文件类型要看文件头魔数——JPEG 的前三个字节是FF D8 FFPNG 是89 50 4E 47GIF 是47 49 46 38。常见做法是在Files.copy前先读前几个字节做比对不匹配直接 400这一步能挡掉大量伪装成图片的可执行文件。3.2 中文文件名下载Content-Disposition 双写法与编码细节上一章的下载代码直接用了file.getFileName()因为存储名是 UUID不会有编码问题。但业务上下载时要还原“原始文件名”比如用户上传了合同扫描件.png下载时要看到这个名字这时候就要处理 HTTP 头的编码约束。HTTP 头的历史包袱是只能传输 ASCII 字符。直接往Content-Disposition里塞中文浏览器会按 ISO-8859-1 解码结果就是一团乱码或者直接显示成%E5%90%88%E5%90%8C之类的串。兼容性最好的写法是同时给出两套值String originalName 合同扫描件.png; String encoded URLEncoder.encode(originalName, StandardCharsets.UTF_8) .replace(, %20); // URLEncoder 会把空格转成 HTTP 头里要还原成 %20 resp.setHeader(Content-Disposition, attachment; filename\ encoded \; filename*UTF-8 encoded);第一个filename是老写法给老版 Safari、Edge 用第二个filename*是 RFC 5987 规定的扩展写法现代 Chrome、Firefox 认它能正确还原中文。URLEncoder.encode之后需要把替换成%20否则文件名里的空格会变成加号这是最常见的细节翻车点。注意filename*的值不需要加引号老写法的filename要加两套值拼在同一个 Header 里逗号分隔。这段逻辑建议封装成一个buildContentDisposition(String fileName)静态方法项目中所有下载接口复用。上传时还要考虑一个问题用户可能上传一个带/或\的原始文件名用于攻击路径。处理办法是存库前只保留最后的文件名片段遇到/就截断再配合上一章说的 UUID 存储名基本能堵死路径注入。3.3 图片压缩与缩略图ImageIO 的参数与落盘时机很多项目到了线上才发现存储空间增长快得吓人一台 500GB 的机器半年就被用户上传的原图塞满。服务端压缩不是可选项而是大流量应用的必选项。Java 原生javax.imageio.ImageIO就够用不需要引额外依赖。// 先落盘原图再基于磁盘文件生成缩略图 Path source Paths.get(BASE_DIR.toString(), dateDir, storedName); BufferedImage original ImageIO.read(source.toFile()); int width 320; int height (int) (original.getHeight() * (width * 1.0 / original.getWidth())); BufferedImage thumbnail new BufferedImage(width, height, BufferedImage.TYPE_INT_RGB); Graphics2D g thumbnail.createGraphics(); g.setRenderingHint(RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BILINEAR); g.drawImage(original, 0, 0, width, height, null); g.dispose(); ImageIO.write(thumbnail, jpg, BASE_DIR.resolve(dateDir).resolve(thumb_ storedName).toFile());缩略图生成的时机建议在文件落盘、事务提交之后异步执行不要同步阻塞在上传请求里。用户上传一张 10MB 原图压缩可能耗时几百毫秒到一两秒如果放在请求里接口 RT 会明显变慢。常见做法是上传接口只落盘原图并返回成功后端用线程池或消息队列消费缩略图生成任务。JPEG 质量参数如果要用ImageWriter控制写法是param.setCompressionMode(ImageWriteParam.MODE_EXPLICIT)配合setCompressionQuality(0.8f)0.8 左右是视觉无损和体积的平衡点低于 0.6 会出现明显的色块和振铃效应。4. 避坑上传下载最容易翻车的五个位置4.1 上传成功但图片打不开文件头损坏与“用错了输出流”现象上传接口返回 200文件也出现在服务器目录里但用图片查看器打开提示“文件已损坏”或“无法识别”。原因有三类。第一用resp.getWriter()写了二进制数据——Writer 是按字符编码输出的会把字节流破坏必须用resp.getOutputStream()。第二复制流时没有正确关闭最后一段数据没有 flush 到磁盘。第三Files.copy的目标路径没有创建父目录中途抛异常但接口被全局异常处理器吞掉返回了一个空壳文件。解决写文件的代码一律用 try-with-resourcesFiles.copy(part.getInputStream(), target, REPLACE_EXISTING)是首选它内部会处理流的关闭如果手写循环读字节记得在 finally 里关流并调用OutputStream.flush()。上传后可以顺手读回文件头校验一下魔数确认落盘文件真的是图片这个动作能自动发现前两类问题。4.2 下载文件名乱码一个表头引发的中文兼容性问题现象文件下载成功但保存时文件名变成____.jpg、%E5%90%88%E5%90%8C.png或直接乱码。原因和 3.2 节讲的一致——Content-Disposition头里的非 ASCII 字符没有正确编码或者只写了老式filename没写filename*。不同浏览器对这个头的实现并不一样Chrome 读filename*老版 Edge 读filename只写其中一种必然有用户中招。解决按 3.2 节的双写法统一封装filename用 URL 编码后的值加引号filename*用UTF-8前缀加同样的编码值。如果项目中所有文件都是 UUID 存储名下载时想还原原始名记得从数据库或缓存里查不要自己拼。4.3 下载回来的是 HTML 而不是图片拦截器与静态资源匹配现象浏览器下载一个.jpg保存后双击打开却是网页源码或登录页。原因通常是请求被拦截器拦了。Spring Security 的会话过期会 302 跳转登录页网关会重写路径或者项目的静态资源处理器把/file/*当成静态目录优先返回了index.html。下载接口本身没写错但请求根本没走到业务代码里。解决先用curl -v或浏览器开发者工具看响应头。如果返回Content-Type: text/html且状态码是 302基本可以断定是拦截器的问题。让下载路径跳过登录验证——注意是跳过“鉴权”而不是跳过“权限”下载的资源如果有保密等级要在业务代码里查当前用户权限不能简单放行。排查静态资源匹配时看看框架里有没有把/file/**映射到classpath:/static/这样的配置。4.4 Windows 上跑得好好的Linux 上线就找不到目录现象本地 IDEA 里上传下载一切正常部署到 Linux 服务器后上传报NoSuchFileException或者下载一直 404。原因是代码里用了 Windows 风格路径拼接比如BASE_DIR \\ dateDir \\ storedName或者用了File.separator。Windows 和 Linux 的路径分隔符不同把\写死到 Linux 上就会拼出/upload\20240812这样的无效路径。解决路径拼接不要手写分隔符用Path.resolve()或Paths.get()。Paths.get(BASE_DIR, dateDir, storedName)会自动根据当前操作系统的分隔符处理。另外注意 BASE_DIR 不要用user.dir这种受启动目录影响的值生产环境建议从配置文件或环境变量读这样即使部署路径变了也不用改代码重新编译。4.5 小图正常、大图一传就 500分片阈值与容器临时目录现象1MB 的图传得上去8MB 的图一传就报 500或者报IllegalStateException: The multi-part request contained parameter data that exceeded the configured limit。原因是MultipartConfig里的maxFileSize或maxRequestSize设置过小文件超限后容器直接抛异常。另一个隐蔽原因是 Tomcat 的临时目录/tmp权限不对文件超过fileSizeThreshold后容器要写到临时目录写不进去就失败。解决把大小限制调到业务合理值通常单文件 5MB、请求体 10MB 对图片场景够用。如果业务确需传大图建议改走分片上传或对象存储而不是无限调大 Tomcat 限制——过大的请求体会长时间占用连接线程高并发下直接把 Tomcat 线程池打死。临时目录的问题可以通过在MultipartConfig里指定location属性指向一个确认可写的目录来解决或者检查/tmp的权限和可用空间。5. 进阶304 缓存、缩略图配合 curl 十秒自测法5.1 给下载接口加 304 缓存减少大图重复传输图片下载和文本接口不一样它是一次请求返回几百 KB 到几 MB 的二进制数据同一个图片反复请求对带宽消耗很大。常见做法是在下载接口里基于文件的最后修改时间和大小生成一个 ETaglong lastModified Files.getLastModifiedTime(file).toMillis(); long fileSize Files.size(file); String etag \ fileSize - lastModified \; // 浏览器带着上次的 ETag 过来直接 304不写响应体 String ifNoneMatch req.getHeader(If-None-Match); if (etag.equals(ifNoneMatch)) { resp.setStatus(304); return; } resp.setHeader(ETag, etag); resp.setHeader(Content-Disposition, attachment; filename\ file.getFileName() \); resp.setContentLengthLong(fileSize);lastModified和fileSize能基本唯一地标识一个文件版本同一张图片第二次请求时浏览器会带If-None-Match服务端比对一致就直接返回 304。别用随机 UUID 当 ETag每次都不一样缓存就形同虚设了。这一步对图片这种“不常变化”的资源收益非常明显能省下大部分重复下载流量。5.2 一套 curl 命令不打开浏览器验证上传下载全链路很多同学习惯用浏览器或 Postman 测上传但浏览器没法看到异常状态码背后的响应头。我测上传接口有一套固定命令# 上传一张测试图-F 里 表示文件路径 curl -v -F file/tmp/test.jpg http://localhost:8080/file/upload # 将上面返回的 url 参数拼到下载地址加 -O 保存为文件 curl -v -O http://localhost:8080/file/download?name20240812/9f2c1a3b.jpg-v会打印完整请求响应头能看到 Content-Disposition 是否带了 attachment、Content-Type 是否被正确识别、状态码是 200 还是 304。上传后拿file命令看落盘文件的真实类型file /path/to/upload/20240812/9f2c1a3b.jpg如果输出是JPEG image data而不是ASCII text或empty说明文件头没问题。这套验证做完基本能把上传、落盘、读取、响应头四段链路全部覆盖。我现在的习惯是任何上传接口改动后先跑这三条命令再交给测试同学省得反反复复被打回来说文件打不开。图片这块的坑多数不是接口逻辑复杂而是 IO、编码和路径三件事没做干净希望这套自测法能帮你在上线前多挡住几刀。本文还有配套的精品资源点击获取