图片上传功能看似简单，但涉及前端编码、后端解析、文件校验、存储策略和异常处理多个环节。使用Spring Boot时，MultipartFile接口封装了上传文件的元数据与字节流，但直接把它写入磁盘会带来诸多隐患。本文从零实现一个可复用的图片上传工具，覆盖从表单提交到落盘的完整链路。

一、前端请求编码与后端参数绑定

浏览器向Java服务端上传图片时，表单的 enctype 必须设置为 multipart/form-data，否则文件内容不会随请求体发送。使用原生HTML时，<form> 标签需要声明 method="post" 和 enctype="multipart/form-data"，并放置一个 <input type="file" name="file">。如果使用 axios 或 fetch，应通过 FormData 对象 append 文件字段。

Spring Boot 默认已启用 multipart 支持，但需要根据业务调整大小限制。在 application.yml 中配置 spring.servlet.multipart.max-file-size 和 max-request-size，例如单文件限制 2MB，总请求限制 5MB。控制器方法用 @RequestParam("file") 接收 MultipartFile 参数，参数名必须与前端字段一致。MultipartFile 提供 getOriginalFilename、getContentType、getSize、getInputStream 等方法，后续校验和保存都会依赖这些方法。

下面是一个基础配置和控制器的示例：

spring:
  servlet:
    multipart:
      max-file-size: 2MB
      max-request-size: 5MB

import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import org.springframework.http.ResponseEntity;
@RestController
@RequestMapping("/api")
public class UploadController {
    @PostMapping("/upload")
    public ResponseEntity<String> upload(@RequestParam("file") MultipartFile file) {
        if (file.isEmpty()) {
            return ResponseEntity.badRequest().body("上传文件不能为空");
        }
        return ResponseEntity.ok("文件接收成功，大小：" + file.getSize());
    }
}

这里的接口返回字符串，实际项目中可以返回JSON结构，例如包含文件URL和文件ID。前端需要根据返回的状态码和内容判断是否上传成功，而不是只判断HTTP状态200。

二、图片真实类型与尺寸校验，避免伪装文件

只检查扩展名是远远不够的。攻击者可以把一个 HTML 或 JS 文件改名为 photo.jpg 上传，如果后续直接以原文件名存储并返回访问地址，就可能触发存储型 XSS 或中间件解析漏洞。正确的做法是读取文件内容的头部魔数来识别真实类型。JPEG 文件以 FF D8 FF 开头，PNG 以 89 50 4E 47 开头，GIF 以 47 49 46 38 开头。

除了魔数，还应当用 Java 的 ImageIO 尝试解码图片，确认文件可以正常解析并获取宽高。这里有一个容易忽略的坑：ImageIO.read 会消耗输入流，一旦读取后，后续再用 file.getInputStream() 保存文件就取不到内容。因此在实现中应先把 MultipartFile 的字节读入 byte[]，基于字节数组做魔数检测和图片解码，最后直接从 byte[] 写入磁盘，避免重复读取流。

以下代码展示了魔数检测和尺寸校验的核心逻辑：

import javax.imageio.ImageIO;
import java.awt.image.BufferedImage;
import java.io.ByteArrayInputStream;
import java.io.IOException;
public class ImageValidator {
    public static boolean isAllowedType(byte[] data) {
        if (data.length < 4) return false;
        // JPEG: FF D8 FF
        if ((data[0] & 0xFF) == 0xFF && (data[1] & 0xFF) == 0xD8 && (data[2] & 0xFF) == 0xFF) {
            return true;
        }
        // PNG: 89 50 4E 47
        if ((data[0] & 0xFF) == 0x89 && data[1] == 0x50 && data[2] == 0x4E && data[3] == 0x47) {
            return true;
        }
        // GIF: 47 49 46 38
        if (data[0] == 0x47 && data[1] == 0x49 && data[2] == 0x46 && data[3] == 0x38) {
            return true;
        }
        return false;
    }
    public static int[] getSize(byte[] data) throws IOException {
        try (ByteArrayInputStream bis = new ByteArrayInputStream(data)) {
            BufferedImage image = ImageIO.read(bis);
            if (image == null) {
                throw new IOException("无法解析图片");
            }
            return new int[]{image.getWidth(), image.getHeight()};
        }
    }
}

业务代码中可以设置白名单和尺寸上限，例如只允许 JPEG、PNG、GIF，宽度和高度不超过 4000 像素。校验不通过直接返回 400 错误，避免无效文件占用存储空间，同时降低图片炸弹攻击的风险。

三、安全重命名与路径规划，杜绝路径穿越

原始文件名是不可信的，可能包含 ../ 路径穿越片段，或者带有空格、中文、特殊符号导致文件系统或Web服务器解析异常。上传后应生成新的文件名，例如使用 UUID 去掉横线再加后缀。后缀不能直接取原始扩展名，应该根据前面识别的真实类型映射，比如 JPEG 对应 .jpg，PNG 对应 .png。这样即使攻击者上传一个名为 x.jsp 的图片，最终存储的也是 .jpg 结尾。

存储目录建议按日期分片，例如 upload/2025/12/01/，避免单目录文件数量过多影响文件系统性能。拼接路径时不要手动使用字符串连接原始文件名，应使用 Paths.get 和 resolve 方法。在写入前调用 normalize 并检查目标路径是否仍位于根目录内，防止路径穿越。

下面是一个安全的保存示例：

import java.nio.file.*;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.UUID;
public class StorageService {
    private final Path root = Paths.get("C:\\uploads\\images");
    public String save(byte[] data, String ext) throws Exception {
        String datePath = new SimpleDateFormat("yyyy/MM/dd").format(new Date());
        Path dir = root.resolve(datePath).normalize();
        if (!dir.startsWith(root)) {
            throw new SecurityException("非法目录");
        }
        Files.createDirectories(dir);
        String newName = UUID.randomUUID().toString().replace("-", "") + "." + ext;
        Path target = dir.resolve(newName).normalize();
        if (!target.getParent().equals(dir)) {
            throw new SecurityException("非法文件名");
        }
        Files.write(target, data, StandardOpenOption.CREATE_NEW);
        return target.toString().replace("\\", "/");
    }
}

代码中的 root 路径使用了 Windows 风格的反斜杠，对应目录 C:\uploads\images，在 Java 字符串中需要写双反斜杠。如果要部署到 Linux 服务器，可以把路径改为 /data/uploads/images，逻辑完全一致。生成的新文件名不包含任何用户输入内容，从根源上避免了路径穿越。

四、完整上传接口与存储层抽象

把前面的校验和保存逻辑整合进 Service，再通过 Controller 调用，就能得到一个可用的图片上传接口。上传流程依次为：检查空文件、检查大小、读取字节数组、魔数校验、尺寸校验、生成新文件名并保存、返回可访问地址。任何一步失败都抛出业务异常，由全局异常处理器返回统一的 JSON 错误信息。

完整的 Service 代码如下：

import org.springframework.stereotype.Service;
import org.springframework.web.multipart.MultipartFile;
@Service
public class ImageUploadService {
    private final StorageService storageService;
    public ImageUploadService(StorageService storageService) {
        this.storageService = storageService;
    }
    public String upload(MultipartFile file) throws Exception {
        if (file.isEmpty()) {
            throw new IllegalArgumentException("文件不能为空");
        }
        long maxSize = 2 * 1024 * 1024;
        if (file.getSize() > maxSize) {
            throw new IllegalArgumentException("文件大小超出2MB限制");
        }
        byte[] data = file.getBytes();
        if (!ImageValidator.isAllowedType(data)) {
            throw new IllegalArgumentException("不支持的图片格式");
        }
        int[] size = ImageValidator.getSize(data);
        if (size[0] > 4000 || size[1] > 4000) {
            throw new IllegalArgumentException("图片尺寸超出4000x4000限制");
        }
        String ext = "jpg"; // 简化为默认，实际应根据魔数映射
        return storageService.save(data, ext);
    }
}

Controller 里注入 ImageUploadService，调用 upload 方法并返回 JSON。真实项目中还需要加入接口限流、登录鉴权和操作日志。图片上传接口经常被恶意扫描，应该配合网关或过滤器限制单 IP 每分钟请求次数。

如果未来需要把图片存储到 OSS 或 MinIO，只需要新增一个实现相同 StorageService 接口的云存储类，把文件字节上传到对象存储并返回 URL，校验逻辑完全不用改。这种存储抽象能让本地开发和生产环境平滑切换，也方便后续做 CDN 加速。