简介这份资源面向Java后端初学者与需要为富文本编辑器接入图片服务的开发者围绕Spring Boot环境讲解图片上传与下载的完整实现思路并重点对接ckeditor4的后端上传接口。压缩包共71个文件以35个java源码、18个class文件、7个xml与6个yml配置为主另含properties配置、jar依赖与gitignore等整体约133KB结构紧凑便于直接导入IDE运行调试。内容涵盖MultipartFile文件接收、上传目录规划、文件名重命名与路径遍历防护、异常处理以及ckeditor4所需的RESTful接口与JSON响应格式、CORS跨域设置下载侧则涉及静态资源映射、权限校验与防盗链思路并延伸至云存储、缩略图生成和日志记录等优化方向。已有235人学习适合作为快速搭建图片管理功能的参考模板也可据此排查上传失败、跨域报错等常见问题。1. 从一次“图片传不上去”的线上事故说起文件上传下载是 Java Web 里最不起眼、却最容易在关键时刻翻车的功能。我见过一个后台管理系统本地测试一切正常上线后运营传一张 3MB 的商品图接口直接返回 500日志里躺着MaxUploadSizeExceededException也见过下载接口把整个文件读进byte[]再写回响应两个人同时下载就把堆内存顶到报警。图片上传与下载看着简单真正落地要处理的是存储路径、文件名冲突、大小限制、类型校验、流式读写、并发和清理这一整套东西。这篇笔记只围绕一个目标用最朴素的 Java 技术栈把图片上传与下载跑通并且跑得能上生产。技术选型上我用 Spring Boot 作为 Web 层因为它对MultipartFile的封装最省事同时把底层Servlet的Part机制讲清楚这样你换成纯 Servlet 或其它框架也能迁移。适合正在做课程设计、后台管理、内容管理系统的同学也适合工作几年但一直用现成组件、没自己捋过文件流的工程师。读完你能拿到一套可复制的目录结构、参数配置和排错清单。2. 上传下载的底层链路从 MultipartFile 到磁盘文件2.1 一次上传请求到底经过了什么浏览器提交一个带图片的form表单时请求头里会带上Content-Type: multipart/form-data; boundary----WebKitFormBoundaryXXXX。这个boundary是分隔符服务端靠它把请求体切成若干段每段对应一个表单字段图片就是其中一段二进制内容。Servlet 规范从 3.0 开始内置了 multipart 解析能力Spring 在此基础上封装成MultipartFile你拿到的getBytes()、getInputStream()、getOriginalFilename()都是从这个解析结果里来的。理解这条链路的意义在于上传失败的位置不同排查方向完全不同。如果请求还没进 Controller 就被拦下多半是容器或框架的大小限制如果进了 Controller 但文件是空的多半是表单enctype写错或字段名对不上如果写磁盘时报错那是路径权限或磁盘空间问题。很多人一遇到上传失败就到处加配置其实先看异常堆栈落在哪一层能省一半时间。下载则是反向的服务端设置响应头Content-Type和Content-Disposition然后把文件字节流写进HttpServletResponse.getOutputStream()。这里的关键是不要一次性把文件读进内存尤其是图片批量下载或大图场景流式拷贝才是正确姿势。2.2 存储方案怎么选本地磁盘、对象存储还是数据库新手最容易纠结的是图片存哪。三种常见方案各有边界方案适用场景主要问题本地磁盘单机部署、课程设计、内网系统多实例无法共享扩容迁移麻烦对象存储生产环境、多实例、CDN 加速需要额外 SDK 和网络配置数据库 BLOB极小文件、强事务一致性要求数据库膨胀快备份恢复慢我的建议是学习和中小项目先用本地磁盘但把存储层抽象成一个接口比如FileStorageService本地实现叫LocalFileStorageService。这样以后换对象存储只改一个实现类Controller 不用动。这个抽象成本很低却是后期最值钱的一步。数据库存图片这条路除非你有非常明确的强一致需求否则不要碰我踩过一次一个 20GB 的库备份要四十分钟血泪经验。2.3 最小可运行的上传接口先看依赖Spring Boot 项目只需要 Web 起步依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency然后是上传接口本身RestController RequestMapping(/api/file) public class FileController { // 上传根目录生产环境应配置到 application.yml不要硬编码 private static final String UPLOAD_DIR /data/upload/; PostMapping(/upload) public MapString, Object upload(RequestParam(file) MultipartFile file) throws IOException { // 1. 空文件校验前端漏传或字段名写错都会走到这里 if (file.isEmpty()) { throw new IllegalArgumentException(上传文件为空); } // 2. 原始文件名可能带路径必须只取文件名部分防止目录穿越 String original StringUtils.cleanPath(file.getOriginalFilename()); // 3. 用 UUID 重命名避免同名覆盖和中文名编码问题 String ext original.substring(original.lastIndexOf(.)); String storedName UUID.randomUUID().toString().replace(-, ) ext; File dir new File(UPLOAD_DIR); if (!dir.exists() !dir.mkdirs()) { throw new IOException(创建上传目录失败); } File dest new File(dir, storedName); // 4. transferTo 底层是流拷贝比 getBytes 再写省内存 file.transferTo(dest); MapString, Object result new HashMap(); result.put(storedName, storedName); result.put(size, file.getSize()); return result; } }逻辑说明第 2 步的StringUtils.cleanPath来自 Spring 的org.springframework.util它会处理..和多余斜杠是防目录穿越的第一道闸。第 3 步用 UUID 重命名是行业惯例原始文件名只存数据库做展示不参与磁盘路径。第 4 步transferTo在 Spring 里对大于阈值的文件会走临时文件移动比手动getInputStream拷贝更稳。参数说明RequestParam(file)里的file必须和前端表单的name属性完全一致这是新手最高频的翻车点。UPLOAD_DIR结尾的斜杠别省new File(dir, name)虽然能处理但混用字符串拼接时容易出问题。2.4 下载接口与响应头设置GetMapping(/download/{storedName}) public void download(PathVariable String storedName, HttpServletResponse response) throws IOException { // 1. 路径参数同样要校验禁止包含斜杠和 .. if (storedName.contains(/) || storedName.contains(..)) { response.setStatus(HttpServletResponse.SC_BAD_REQUEST); return; } File file new File(UPLOAD_DIR, storedName); if (!file.exists()) { response.setStatus(HttpServletResponse.SC_NOT_FOUND); return; } // 2. 根据扩展名推断 MIME图片要正确设置否则浏览器不预览 String mime Files.probeContentType(file.toPath()); response.setContentType(mime ! null ? mime : application/octet-stream); // 3. inline 表示浏览器内预览attachment 表示强制下载 response.setHeader(Content-Disposition, inline; filename\ URLEncoder.encode(storedName, UTF-8) \); response.setContentLengthLong(file.length()); // 4. 流式拷贝8KB 缓冲区是 IO 的常见经验值 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(); } }逻辑说明第 1 步的路径校验不能省PathVariable虽然不会匹配斜杠但编码后的%2F在某些容器配置下会被还原手动挡一道更保险。第 3 步Content-Disposition里的文件名用URLEncoder编码否则中文名在部分浏览器会乱码。第 4 步用try-with-resources保证流关闭response.getOutputStream()不需要手动关容器会处理但FileInputStream必须关。参数说明缓冲区 8192 字节是通用值图片场景可以调到 16384 减少系统调用次数但收益有限。setContentLengthLong让浏览器能显示下载进度大文件场景建议加上。3. 把上传下载做扎实校验、配置与目录规划3.1 大小限制的三层配置别漏上传大小限制在 Spring Boot 里至少有两层很多人只配了一层就以为完事spring: servlet: multipart: max-file-size: 10MB # 单个文件上限 max-request-size: 20MB # 整个请求上限多文件时要注意 file-size-threshold: 1MB # 超过此值写入临时文件而非内存 location: /data/tmp # 临时文件目录默认是系统临时目录第一层是 Spring 的MultipartConfigElement由上面这些配置生成。第二层是内嵌容器本身比如 Tomcat 的maxSwallowSize它决定请求体被拒绝后容器还愿意读多少数据配小了会出现连接重置而不是友好的 413。第三层是反向代理Nginx 默认client_max_body_size是 1MB前端传 2MB 图片直接 413这个坑我见过太多次排查时先看代理日志。提示file-size-threshold设太小会让所有文件都落临时盘设太大则大文件占内存。1MB 是个平衡点图片场景够用。3.2 文件类型校验别只信扩展名只校验扩展名等于没校验攻击者把.jsp改成.jpg就能绕过。正确做法是读文件头魔数public static boolean isImage(MultipartFile file) throws IOException { // 读取前 8 个字节判断魔数 byte[] header new byte[8]; try (InputStream in file.getInputStream()) { if (in.read(header) 8) { return false; } } // JPEG: FF D8 FF if ((header[0] 0xFF) 0xFF (header[1] 0xFF) 0xD8 (header[2] 0xFF) 0xFF) { return true; } // PNG: 89 50 4E 47 if ((header[0] 0xFF) 0x89 header[1] P header[2] N header[3] G) { return true; } // GIF: 47 49 46 38 if (header[0] G header[1] I header[2] F header[3] 8) { return true; } return false; }逻辑说明 0xFF是把有符号 byte 转成无符号整数再比较Java 的 byte 是有符号的直接和0xFF比会出错这是很多人写魔数校验时的隐藏 bug。这个方法只覆盖 JPEG、PNG、GIF 三种常见格式WebP 的魔数是RIFF....WEBP需要读 12 字节按需扩展。参数说明读流之前要判断file.getSize()太小的文件直接拒绝避免read返回 -1 时的边界问题。校验完记得流会被消费如果后面还要用transferToSpring 的MultipartFile支持重复读取临时文件模式但内存模式下的实现要小心建议校验和保存分开处理。3.3 目录规划按日期分片别堆一个目录所有图片扔一个目录文件数上万后ls都卡备份和迁移也痛苦。常见做法是按日期分片public static String buildRelativePath(String storedName) { // 按 yyyy/MM/dd 分三级目录单目录文件数可控 LocalDate now LocalDate.now(); String datePath now.format(DateTimeFormatter.ofPattern(yyyy/MM/dd)); return datePath / storedName; }逻辑说明yyyy/MM/dd三级目录按每天一万张图算单目录也就一万个文件文件系统完全扛得住。数据库里存相对路径读取时拼上根目录这样迁移存储根目录不用改数据。参数说明分片粒度可以按业务调整图片量小的系统用yyyy/MM就够量大的用yyyy/MM/dd/HH。关键是分片规则一旦上线不要改否则老数据找不到这是后悔药都买不到的事。3.4 用数据库记录文件元信息磁盘上只有文件不够业务上通常要记录谁传的、什么时候传的、原始文件名是什么CREATE TABLE sys_file ( id BIGINT PRIMARY KEY AUTO_INCREMENT, stored_name VARCHAR(64) NOT NULL COMMENT 磁盘存储名, original_name VARCHAR(255) NOT NULL COMMENT 原始文件名, relative_path VARCHAR(255) NOT NULL COMMENT 相对路径, content_type VARCHAR(128) COMMENT MIME 类型, file_size BIGINT NOT NULL COMMENT 字节数, uploader_id BIGINT COMMENT 上传人, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_stored_name (stored_name) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;逻辑说明stored_name加唯一索引防止极端情况下 UUID 碰撞概率极低但成本几乎为零。relative_path存相对路径而不是绝对路径是为了迁移时只改配置。original_name用utf8mb4存中文和 emoji 都不会出问题。参数说明file_size用BIGINT而不是INTINT上限约 2GB虽然图片到不了但统一用BIGINT省得以后改表。content_type存下来方便下载时直接设置响应头不用每次重新探测。4. 上传下载的避坑清单五个真实翻车现场4.1 现象接口返回 500日志是 MaxUploadSizeExceededException原因spring.servlet.multipart.max-file-size没配或配小了默认值在部分版本里只有 1MB。前端传的图片超过限制Spring 在解析阶段就抛异常还没进 Controller。解决在application.yml里显式配置max-file-size和max-request-size并且加一个全局异常处理器把MaxUploadSizeExceededException转成友好的 413 响应别让用户看到 500 堆栈。同时检查 Nginx 的client_max_body_size两层都要放开。4.2 现象文件传上来了但大小是 0 字节原因前端表单没写enctypemultipart/form-data或者RequestParam的名字和表单name对不上。还有一种情况是用了RequestBody接MultipartFile这是接不到的multipart 必须用RequestParam或RequestPart。解决先看浏览器开发者工具里的请求体确认是 multipart 格式且字段名正确。后端把RequestParam(file)的名字和前端对齐大小写敏感。用 Postman 测试时注意选form-data而不是x-www-form-urlencoded。4.3 现象中文文件名下载后变成乱码原因Content-Disposition里的文件名没编码HTTP 头默认按 ISO-8859-1 解析中文直接乱。不同浏览器对编码方式的支持还不一致。解决用URLEncoder.encode(name, UTF-8)编码并且把空格替换成%20而不是。更稳妥的写法是同时提供filename和filename*UTF-8两个参数兼容老浏览器。这个坑没有银弹测试时至少覆盖 Chrome 和 Edge。4.4 现象并发下载大图时内存飙升原因下载接口用了Files.readAllBytes或file.getBytes()把整个文件读进内存单文件 10MB十个并发就是 100MB 堆占用图片再大点直接 OOM。解决改成流式拷贝用固定大小缓冲区循环读写。响应头里设置Content-Length让浏览器知道总大小。如果图片需要压缩或加水印也要用流式处理库别先读全量再处理。4.5 现象上传目录权限不足Linux 上报 Permission denied原因应用以非 root 用户运行UPLOAD_DIR指向的目录属主是 root或者目录不存在且父目录不可写。Windows 本地测试正常一上 Linux 就翻车。解决部署时用chown -R appuser:appuser /data/upload把目录给应用用户mkdir -p确保父目录存在。代码里mkdirs失败要抛明确异常别吞掉。容器部署时注意挂载卷的权限readOnly挂载是写不进去的。5. 进阶技巧用断点续传和图片压缩把体验拉满基础功能跑通后真正拉开差距的是两个点大图上传的稳定性和下载的响应速度。先说上传普通表单上传在网络抖动时会整个失败重来用户体验很差。一个轻量做法是前端分片、后端合并核心逻辑是记录已上传的分片序号全部到齐后按序拼接PostMapping(/chunk) public MapString, Object uploadChunk(RequestParam(chunk) MultipartFile chunk, RequestParam(index) int index, RequestParam(total) int total, RequestParam(md5) String md5) throws IOException { // 每个文件用 md5 建临时目录分片按序号命名 File chunkDir new File(UPLOAD_DIR chunks/ md5); if (!chunkDir.exists() !chunkDir.mkdirs()) { throw new IOException(创建分片目录失败); } chunk.transferTo(new File(chunkDir, String.valueOf(index))); // 检查是否所有分片都到齐 File[] chunks chunkDir.listFiles(); if (chunks ! null chunks.length total) { // 按序号排序后顺序写入最终文件 Arrays.sort(chunks, Comparator.comparingInt(f - Integer.parseInt(f.getName()))); File target new File(UPLOAD_DIR, md5 .jpg); try (OutputStream out new FileOutputStream(target)) { for (File c : chunks) { Files.copy(c.toPath(), out); } } // 合并完清理临时分片避免磁盘堆积 for (File c : chunks) { c.delete(); } chunkDir.delete(); } return Collections.singletonMap(received, index); }逻辑说明用文件 md5 做临时目录名天然去重同一文件重复上传不会冲突。分片按数字序号命名合并前必须排序否则图片会错位这是分片上传最经典的 bug。合并用Files.copy追加写入比手动读字节数组简洁。合并后清理临时文件否则磁盘会被分片撑爆。参数说明index从 0 或 1 开始要前后端约定一致我一般用 0。total是分片总数前端按固定分片大小比如 2MB算出来。md5建议前端算大文件后端算太慢。分片大小别太小1MB 以下会产生大量请求2MB 到 5MB 比较合适。再说下载侧的图片压缩。原图动辄几 MB列表页展示根本不需要那么高分辨率。常见做法是上传时生成一张缩略图下载接口根据参数返回不同尺寸public static void writeThumbnail(File source, OutputStream out, int maxWidth) throws IOException { BufferedImage image ImageIO.read(source); if (image null) { throw new IOException(无法解析图片); } // 按宽度等比缩放高度自动计算 int width Math.min(image.getWidth(), maxWidth); int height image.getHeight() * width / image.getWidth(); BufferedImage thumb new BufferedImage(width, height, BufferedImage.TYPE_INT_RGB); Graphics2D g thumb.createGraphics(); // 开启抗锯齿缩放后不会太糊 g.setRenderingHint(RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BILINEAR); g.drawImage(image, 0, 0, width, height, null); g.dispose(); ImageIO.write(thumb, jpg, out); }逻辑说明ImageIO.read对某些 CMYK 模式的 JPEG 会返回 null所以必须判空。缩放用Graphics2D的drawImage一步到位比先getScaledInstance再画性能好。TYPE_INT_RGB会丢掉透明通道PNG 转 JPG 时要注意需要透明就换TYPE_INT_ARGB。参数说明maxWidth按场景定列表缩略图 200 到 400 像素够用详情页预览 800 到 1200 像素。抗锯齿用BILINEAR是速度和质量的平衡点BICUBIC更清晰但慢图片量大时慎用。输出格式统一用 JPG 体积小但透明图要保留 PNG。最后说一个验证习惯每次改完上传下载相关代码我都会用三种方式各测一遍——Postman 传正常图、传一个改了扩展名的非图片文件、传一个超过限制的大文件。这三个用例能覆盖八成以上的线上问题。图片上传下载这活儿写起来半天写扎实要踩不少坑但把存储抽象、流式读写、魔数校验这几件事做对后面基本不用再回头改。希望帮到你。本文还有配套的精品资源点击获取
Java图片上传下载实战：从MultipartFile到生产级避坑指南
简介这份资源面向Java后端初学者与需要为富文本编辑器接入图片服务的开发者围绕Spring Boot环境讲解图片上传与下载的完整实现思路并重点对接ckeditor4的后端上传接口。压缩包共71个文件以35个java源码、18个class文件、7个xml与6个yml配置为主另含properties配置、jar依赖与gitignore等整体约133KB结构紧凑便于直接导入IDE运行调试。内容涵盖MultipartFile文件接收、上传目录规划、文件名重命名与路径遍历防护、异常处理以及ckeditor4所需的RESTful接口与JSON响应格式、CORS跨域设置下载侧则涉及静态资源映射、权限校验与防盗链思路并延伸至云存储、缩略图生成和日志记录等优化方向。已有235人学习适合作为快速搭建图片管理功能的参考模板也可据此排查上传失败、跨域报错等常见问题。1. 从一次“图片传不上去”的线上事故说起文件上传下载是 Java Web 里最不起眼、却最容易在关键时刻翻车的功能。我见过一个后台管理系统本地测试一切正常上线后运营传一张 3MB 的商品图接口直接返回 500日志里躺着MaxUploadSizeExceededException也见过下载接口把整个文件读进byte[]再写回响应两个人同时下载就把堆内存顶到报警。图片上传与下载看着简单真正落地要处理的是存储路径、文件名冲突、大小限制、类型校验、流式读写、并发和清理这一整套东西。这篇笔记只围绕一个目标用最朴素的 Java 技术栈把图片上传与下载跑通并且跑得能上生产。技术选型上我用 Spring Boot 作为 Web 层因为它对MultipartFile的封装最省事同时把底层Servlet的Part机制讲清楚这样你换成纯 Servlet 或其它框架也能迁移。适合正在做课程设计、后台管理、内容管理系统的同学也适合工作几年但一直用现成组件、没自己捋过文件流的工程师。读完你能拿到一套可复制的目录结构、参数配置和排错清单。2. 上传下载的底层链路从 MultipartFile 到磁盘文件2.1 一次上传请求到底经过了什么浏览器提交一个带图片的form表单时请求头里会带上Content-Type: multipart/form-data; boundary----WebKitFormBoundaryXXXX。这个boundary是分隔符服务端靠它把请求体切成若干段每段对应一个表单字段图片就是其中一段二进制内容。Servlet 规范从 3.0 开始内置了 multipart 解析能力Spring 在此基础上封装成MultipartFile你拿到的getBytes()、getInputStream()、getOriginalFilename()都是从这个解析结果里来的。理解这条链路的意义在于上传失败的位置不同排查方向完全不同。如果请求还没进 Controller 就被拦下多半是容器或框架的大小限制如果进了 Controller 但文件是空的多半是表单enctype写错或字段名对不上如果写磁盘时报错那是路径权限或磁盘空间问题。很多人一遇到上传失败就到处加配置其实先看异常堆栈落在哪一层能省一半时间。下载则是反向的服务端设置响应头Content-Type和Content-Disposition然后把文件字节流写进HttpServletResponse.getOutputStream()。这里的关键是不要一次性把文件读进内存尤其是图片批量下载或大图场景流式拷贝才是正确姿势。2.2 存储方案怎么选本地磁盘、对象存储还是数据库新手最容易纠结的是图片存哪。三种常见方案各有边界方案适用场景主要问题本地磁盘单机部署、课程设计、内网系统多实例无法共享扩容迁移麻烦对象存储生产环境、多实例、CDN 加速需要额外 SDK 和网络配置数据库 BLOB极小文件、强事务一致性要求数据库膨胀快备份恢复慢我的建议是学习和中小项目先用本地磁盘但把存储层抽象成一个接口比如FileStorageService本地实现叫LocalFileStorageService。这样以后换对象存储只改一个实现类Controller 不用动。这个抽象成本很低却是后期最值钱的一步。数据库存图片这条路除非你有非常明确的强一致需求否则不要碰我踩过一次一个 20GB 的库备份要四十分钟血泪经验。2.3 最小可运行的上传接口先看依赖Spring Boot 项目只需要 Web 起步依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency然后是上传接口本身RestController RequestMapping(/api/file) public class FileController { // 上传根目录生产环境应配置到 application.yml不要硬编码 private static final String UPLOAD_DIR /data/upload/; PostMapping(/upload) public MapString, Object upload(RequestParam(file) MultipartFile file) throws IOException { // 1. 空文件校验前端漏传或字段名写错都会走到这里 if (file.isEmpty()) { throw new IllegalArgumentException(上传文件为空); } // 2. 原始文件名可能带路径必须只取文件名部分防止目录穿越 String original StringUtils.cleanPath(file.getOriginalFilename()); // 3. 用 UUID 重命名避免同名覆盖和中文名编码问题 String ext original.substring(original.lastIndexOf(.)); String storedName UUID.randomUUID().toString().replace(-, ) ext; File dir new File(UPLOAD_DIR); if (!dir.exists() !dir.mkdirs()) { throw new IOException(创建上传目录失败); } File dest new File(dir, storedName); // 4. transferTo 底层是流拷贝比 getBytes 再写省内存 file.transferTo(dest); MapString, Object result new HashMap(); result.put(storedName, storedName); result.put(size, file.getSize()); return result; } }逻辑说明第 2 步的StringUtils.cleanPath来自 Spring 的org.springframework.util它会处理..和多余斜杠是防目录穿越的第一道闸。第 3 步用 UUID 重命名是行业惯例原始文件名只存数据库做展示不参与磁盘路径。第 4 步transferTo在 Spring 里对大于阈值的文件会走临时文件移动比手动getInputStream拷贝更稳。参数说明RequestParam(file)里的file必须和前端表单的name属性完全一致这是新手最高频的翻车点。UPLOAD_DIR结尾的斜杠别省new File(dir, name)虽然能处理但混用字符串拼接时容易出问题。2.4 下载接口与响应头设置GetMapping(/download/{storedName}) public void download(PathVariable String storedName, HttpServletResponse response) throws IOException { // 1. 路径参数同样要校验禁止包含斜杠和 .. if (storedName.contains(/) || storedName.contains(..)) { response.setStatus(HttpServletResponse.SC_BAD_REQUEST); return; } File file new File(UPLOAD_DIR, storedName); if (!file.exists()) { response.setStatus(HttpServletResponse.SC_NOT_FOUND); return; } // 2. 根据扩展名推断 MIME图片要正确设置否则浏览器不预览 String mime Files.probeContentType(file.toPath()); response.setContentType(mime ! null ? mime : application/octet-stream); // 3. inline 表示浏览器内预览attachment 表示强制下载 response.setHeader(Content-Disposition, inline; filename\ URLEncoder.encode(storedName, UTF-8) \); response.setContentLengthLong(file.length()); // 4. 流式拷贝8KB 缓冲区是 IO 的常见经验值 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(); } }逻辑说明第 1 步的路径校验不能省PathVariable虽然不会匹配斜杠但编码后的%2F在某些容器配置下会被还原手动挡一道更保险。第 3 步Content-Disposition里的文件名用URLEncoder编码否则中文名在部分浏览器会乱码。第 4 步用try-with-resources保证流关闭response.getOutputStream()不需要手动关容器会处理但FileInputStream必须关。参数说明缓冲区 8192 字节是通用值图片场景可以调到 16384 减少系统调用次数但收益有限。setContentLengthLong让浏览器能显示下载进度大文件场景建议加上。3. 把上传下载做扎实校验、配置与目录规划3.1 大小限制的三层配置别漏上传大小限制在 Spring Boot 里至少有两层很多人只配了一层就以为完事spring: servlet: multipart: max-file-size: 10MB # 单个文件上限 max-request-size: 20MB # 整个请求上限多文件时要注意 file-size-threshold: 1MB # 超过此值写入临时文件而非内存 location: /data/tmp # 临时文件目录默认是系统临时目录第一层是 Spring 的MultipartConfigElement由上面这些配置生成。第二层是内嵌容器本身比如 Tomcat 的maxSwallowSize它决定请求体被拒绝后容器还愿意读多少数据配小了会出现连接重置而不是友好的 413。第三层是反向代理Nginx 默认client_max_body_size是 1MB前端传 2MB 图片直接 413这个坑我见过太多次排查时先看代理日志。提示file-size-threshold设太小会让所有文件都落临时盘设太大则大文件占内存。1MB 是个平衡点图片场景够用。3.2 文件类型校验别只信扩展名只校验扩展名等于没校验攻击者把.jsp改成.jpg就能绕过。正确做法是读文件头魔数public static boolean isImage(MultipartFile file) throws IOException { // 读取前 8 个字节判断魔数 byte[] header new byte[8]; try (InputStream in file.getInputStream()) { if (in.read(header) 8) { return false; } } // JPEG: FF D8 FF if ((header[0] 0xFF) 0xFF (header[1] 0xFF) 0xD8 (header[2] 0xFF) 0xFF) { return true; } // PNG: 89 50 4E 47 if ((header[0] 0xFF) 0x89 header[1] P header[2] N header[3] G) { return true; } // GIF: 47 49 46 38 if (header[0] G header[1] I header[2] F header[3] 8) { return true; } return false; }逻辑说明 0xFF是把有符号 byte 转成无符号整数再比较Java 的 byte 是有符号的直接和0xFF比会出错这是很多人写魔数校验时的隐藏 bug。这个方法只覆盖 JPEG、PNG、GIF 三种常见格式WebP 的魔数是RIFF....WEBP需要读 12 字节按需扩展。参数说明读流之前要判断file.getSize()太小的文件直接拒绝避免read返回 -1 时的边界问题。校验完记得流会被消费如果后面还要用transferToSpring 的MultipartFile支持重复读取临时文件模式但内存模式下的实现要小心建议校验和保存分开处理。3.3 目录规划按日期分片别堆一个目录所有图片扔一个目录文件数上万后ls都卡备份和迁移也痛苦。常见做法是按日期分片public static String buildRelativePath(String storedName) { // 按 yyyy/MM/dd 分三级目录单目录文件数可控 LocalDate now LocalDate.now(); String datePath now.format(DateTimeFormatter.ofPattern(yyyy/MM/dd)); return datePath / storedName; }逻辑说明yyyy/MM/dd三级目录按每天一万张图算单目录也就一万个文件文件系统完全扛得住。数据库里存相对路径读取时拼上根目录这样迁移存储根目录不用改数据。参数说明分片粒度可以按业务调整图片量小的系统用yyyy/MM就够量大的用yyyy/MM/dd/HH。关键是分片规则一旦上线不要改否则老数据找不到这是后悔药都买不到的事。3.4 用数据库记录文件元信息磁盘上只有文件不够业务上通常要记录谁传的、什么时候传的、原始文件名是什么CREATE TABLE sys_file ( id BIGINT PRIMARY KEY AUTO_INCREMENT, stored_name VARCHAR(64) NOT NULL COMMENT 磁盘存储名, original_name VARCHAR(255) NOT NULL COMMENT 原始文件名, relative_path VARCHAR(255) NOT NULL COMMENT 相对路径, content_type VARCHAR(128) COMMENT MIME 类型, file_size BIGINT NOT NULL COMMENT 字节数, uploader_id BIGINT COMMENT 上传人, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_stored_name (stored_name) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;逻辑说明stored_name加唯一索引防止极端情况下 UUID 碰撞概率极低但成本几乎为零。relative_path存相对路径而不是绝对路径是为了迁移时只改配置。original_name用utf8mb4存中文和 emoji 都不会出问题。参数说明file_size用BIGINT而不是INTINT上限约 2GB虽然图片到不了但统一用BIGINT省得以后改表。content_type存下来方便下载时直接设置响应头不用每次重新探测。4. 上传下载的避坑清单五个真实翻车现场4.1 现象接口返回 500日志是 MaxUploadSizeExceededException原因spring.servlet.multipart.max-file-size没配或配小了默认值在部分版本里只有 1MB。前端传的图片超过限制Spring 在解析阶段就抛异常还没进 Controller。解决在application.yml里显式配置max-file-size和max-request-size并且加一个全局异常处理器把MaxUploadSizeExceededException转成友好的 413 响应别让用户看到 500 堆栈。同时检查 Nginx 的client_max_body_size两层都要放开。4.2 现象文件传上来了但大小是 0 字节原因前端表单没写enctypemultipart/form-data或者RequestParam的名字和表单name对不上。还有一种情况是用了RequestBody接MultipartFile这是接不到的multipart 必须用RequestParam或RequestPart。解决先看浏览器开发者工具里的请求体确认是 multipart 格式且字段名正确。后端把RequestParam(file)的名字和前端对齐大小写敏感。用 Postman 测试时注意选form-data而不是x-www-form-urlencoded。4.3 现象中文文件名下载后变成乱码原因Content-Disposition里的文件名没编码HTTP 头默认按 ISO-8859-1 解析中文直接乱。不同浏览器对编码方式的支持还不一致。解决用URLEncoder.encode(name, UTF-8)编码并且把空格替换成%20而不是。更稳妥的写法是同时提供filename和filename*UTF-8两个参数兼容老浏览器。这个坑没有银弹测试时至少覆盖 Chrome 和 Edge。4.4 现象并发下载大图时内存飙升原因下载接口用了Files.readAllBytes或file.getBytes()把整个文件读进内存单文件 10MB十个并发就是 100MB 堆占用图片再大点直接 OOM。解决改成流式拷贝用固定大小缓冲区循环读写。响应头里设置Content-Length让浏览器知道总大小。如果图片需要压缩或加水印也要用流式处理库别先读全量再处理。4.5 现象上传目录权限不足Linux 上报 Permission denied原因应用以非 root 用户运行UPLOAD_DIR指向的目录属主是 root或者目录不存在且父目录不可写。Windows 本地测试正常一上 Linux 就翻车。解决部署时用chown -R appuser:appuser /data/upload把目录给应用用户mkdir -p确保父目录存在。代码里mkdirs失败要抛明确异常别吞掉。容器部署时注意挂载卷的权限readOnly挂载是写不进去的。5. 进阶技巧用断点续传和图片压缩把体验拉满基础功能跑通后真正拉开差距的是两个点大图上传的稳定性和下载的响应速度。先说上传普通表单上传在网络抖动时会整个失败重来用户体验很差。一个轻量做法是前端分片、后端合并核心逻辑是记录已上传的分片序号全部到齐后按序拼接PostMapping(/chunk) public MapString, Object uploadChunk(RequestParam(chunk) MultipartFile chunk, RequestParam(index) int index, RequestParam(total) int total, RequestParam(md5) String md5) throws IOException { // 每个文件用 md5 建临时目录分片按序号命名 File chunkDir new File(UPLOAD_DIR chunks/ md5); if (!chunkDir.exists() !chunkDir.mkdirs()) { throw new IOException(创建分片目录失败); } chunk.transferTo(new File(chunkDir, String.valueOf(index))); // 检查是否所有分片都到齐 File[] chunks chunkDir.listFiles(); if (chunks ! null chunks.length total) { // 按序号排序后顺序写入最终文件 Arrays.sort(chunks, Comparator.comparingInt(f - Integer.parseInt(f.getName()))); File target new File(UPLOAD_DIR, md5 .jpg); try (OutputStream out new FileOutputStream(target)) { for (File c : chunks) { Files.copy(c.toPath(), out); } } // 合并完清理临时分片避免磁盘堆积 for (File c : chunks) { c.delete(); } chunkDir.delete(); } return Collections.singletonMap(received, index); }逻辑说明用文件 md5 做临时目录名天然去重同一文件重复上传不会冲突。分片按数字序号命名合并前必须排序否则图片会错位这是分片上传最经典的 bug。合并用Files.copy追加写入比手动读字节数组简洁。合并后清理临时文件否则磁盘会被分片撑爆。参数说明index从 0 或 1 开始要前后端约定一致我一般用 0。total是分片总数前端按固定分片大小比如 2MB算出来。md5建议前端算大文件后端算太慢。分片大小别太小1MB 以下会产生大量请求2MB 到 5MB 比较合适。再说下载侧的图片压缩。原图动辄几 MB列表页展示根本不需要那么高分辨率。常见做法是上传时生成一张缩略图下载接口根据参数返回不同尺寸public static void writeThumbnail(File source, OutputStream out, int maxWidth) throws IOException { BufferedImage image ImageIO.read(source); if (image null) { throw new IOException(无法解析图片); } // 按宽度等比缩放高度自动计算 int width Math.min(image.getWidth(), maxWidth); int height image.getHeight() * width / image.getWidth(); BufferedImage thumb new BufferedImage(width, height, BufferedImage.TYPE_INT_RGB); Graphics2D g thumb.createGraphics(); // 开启抗锯齿缩放后不会太糊 g.setRenderingHint(RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BILINEAR); g.drawImage(image, 0, 0, width, height, null); g.dispose(); ImageIO.write(thumb, jpg, out); }逻辑说明ImageIO.read对某些 CMYK 模式的 JPEG 会返回 null所以必须判空。缩放用Graphics2D的drawImage一步到位比先getScaledInstance再画性能好。TYPE_INT_RGB会丢掉透明通道PNG 转 JPG 时要注意需要透明就换TYPE_INT_ARGB。参数说明maxWidth按场景定列表缩略图 200 到 400 像素够用详情页预览 800 到 1200 像素。抗锯齿用BILINEAR是速度和质量的平衡点BICUBIC更清晰但慢图片量大时慎用。输出格式统一用 JPG 体积小但透明图要保留 PNG。最后说一个验证习惯每次改完上传下载相关代码我都会用三种方式各测一遍——Postman 传正常图、传一个改了扩展名的非图片文件、传一个超过限制的大文件。这三个用例能覆盖八成以上的线上问题。图片上传下载这活儿写起来半天写扎实要踩不少坑但把存储抽象、流式读写、魔数校验这几件事做对后面基本不用再回头改。希望帮到你。本文还有配套的精品资源点击获取
