Spring Boot 与前端文件上传跨域问题：Multipart、CORS 与网关配置

前言

在前后端分离架构下，文件上传 是一个常见功能。但在 Spring Boot 项目中，我们经常会遇到前端调用接口上传文件时出现 跨域问题，表现为：

• 浏览器控制台报错：Access-Control-Allow-Origin 缺失或不匹配。

• 使用 FormData 上传文件时触发 OPTIONS 预检请求失败。

• Spring Boot 的 Multipart 配置不生效，导致请求被拦截。

• 在 API 网关环境下，跨域配置与上传配置冲突，最终上传失败。

本文将从 Multipart 配置 、CORS 处理 和 网关层面 三个维度，深入解析 Spring Boot 文件上传跨域问题，并给出对应的解决方案和最佳实践。

---

1. 文件上传的基本实现

1.1 Spring Boot Controller 代码示例

常见的文件上传接口实现如下：

@RestController
@RequestMapping("/api/file")
public class FileUploadController {

    @PostMapping("/upload")
    public ResponseEntity<String> upload(@RequestParam("file") MultipartFile file) {
        if (file.isEmpty()) {
            return ResponseEntity.badRequest().body("文件为空");
        }
        // 保存文件逻辑（本地 / OSS / MinIO）
        return ResponseEntity.ok("上传成功: " + file.getOriginalFilename());
    }
}

1.2 前端调用（Vue/React 示例）

const formData = new FormData();
formData.append("file", file);

fetch("http://localhost:8080/api/file/upload", {
  method: "POST",
  body: formData,
  credentials: "include" // 如果需要携带 Cookie
}).then(res => res.text()).then(console.log);

问题 ：如果前端和后端端口不同（例如前端 http://localhost:3000，后端 http://localhost:8080），浏览器会直接拦截请求，抛出 CORS 错误。

---

2. 跨域问题的根源

文件上传属于 复杂跨域请求 ，因为其 Content-Type 通常为 multipart/form-data，这会触发 浏览器的预检请求 (OPTIONS)。

2.1 常见报错

• Access to fetch at 'http://localhost:8080/api/file/upload' from origin 'http://localhost:3000' has been blocked by CORS policy

• Response to preflight request doesn't pass access control check

2.2 跨域失败的常见原因

1. Spring Boot 未正确配置 CORS。

2. Multipart 配置未允许跨域请求，导致请求体被拦截。

3. API 网关层（Nginx、Spring Cloud Gateway）未处理 CORS。

4. 前端携带了 Cookie/Authorization 等敏感头，而后端未设置 Access-Control-Allow-Credentials。

---

3. Spring Boot 层面的解决方案

3.1 使用 @CrossOrigin

最简单的方式是在 Controller 层添加注解：

@RestController
@RequestMapping("/api/file")
@CrossOrigin(origins = "http://localhost:3000", allowCredentials = "true")
public class FileUploadController {
    ...
}

但缺点是配置分散，不利于统一管理。

---

3.2 全局 CORS 配置

推荐在 WebMvcConfigurer 中统一配置跨域：

@Configuration
public class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("http://localhost:3000") // 前端地址
                .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                .allowedHeaders("*")
                .allowCredentials(true) // 允许携带 Cookie
                .maxAge(3600);
    }
}

注意：

• allowedOrigins("*") 与 allowCredentials(true) 不能同时使用。

• 如果有多个前端环境（如本地开发和生产前端），建议用配置文件区分。

---

3.3 Multipart 配置优化

在 application.yml 中启用 Multipart：

spring:
  servlet:
    multipart:
      max-file-size: 50MB
      max-request-size: 100MB

⚠️ 常见误区：

• 如果配置过小，浏览器端会直接报错 413 Payload Too Large。

• 某些情况跨域失败其实是文件大小限制触发的异常，而开发者误以为是 CORS 问题。

---

4. 网关层面的跨域配置

在微服务架构下，前端请求通常会先经过 Nginx 或 Spring Cloud Gateway，这时跨域配置需要在网关层处理。

4.1 Nginx 配置示例

location /api/ {
    proxy_pass http://localhost:8080/;
    add_header Access-Control-Allow-Origin http://localhost:3000;
    add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS';
    add_header Access-Control-Allow-Headers 'Content-Type, Authorization';
    add_header Access-Control-Allow-Credentials 'true';
}

4.2 Spring Cloud Gateway 配置

在 application.yml 中添加：

spring:
  cloud:
    gateway:
      globalcors:
        corsConfigurations:
          '[/**]':
            allowedOrigins: "http://localhost:3000"
            allowedMethods:
              - GET
              - POST
              - OPTIONS
            allowedHeaders: "*"
            allowCredentials: true

注意 ：如果网关配置了 CORS，后端服务层的 @CrossOrigin 配置可能会被覆盖，需要统一规范。

---

5. 实战排查思路

1. 确认预检请求 OPTIONS 是否成功

   • 使用浏览器开发者工具查看是否返回 200，且带有 Access-Control-Allow-Origin。

2. 确认文件大小限制是否正确

   • 检查 spring.servlet.multipart.max-file-size 是否过小。

3. 检查 Cookie/Token 配置

   • 如果前端设置了 credentials: include，后端必须配置 allowCredentials(true)，并且不能使用通配符 *。

4. 检查网关与后端的配置是否冲突

   • 在 Nginx 或 Spring Cloud Gateway 中配置时，避免和后端重复处理。

---

6. 最佳实践

• 开发环境：使用 Spring Boot 全局 CORS 配置，快速解决跨域问题。

• 生产环境：推荐通过 Nginx 或 Gateway 层统一配置跨域，避免在多个微服务中重复配置。

• 安全性 ：跨域策略不要随便 * 放开，应针对前端域名精准配置。

• 文件上传：提前规划文件大小限制，并做好异常处理，避免与跨域问题混淆。

---

结语

在 Spring Boot 项目中，文件上传跨域问题 往往涉及 Multipart 配置、CORS 策略和网关层处理 三个层面。常见的坑包括：

• OPTIONS 预检请求未正确响应；

• 配置了 allowedOrigins("*") 但同时开启了 allowCredentials(true)；

• 文件过大被拦截，误判为跨域问题；

• 网关层未配置跨域，导致请求失败。

解决思路是：

• 开发阶段全局配置 CORS；

• 部署时通过网关或 Nginx 统一管理跨域；

• 精准控制允许的前端域名，提升安全性。

✅ 至此，你已经掌握了 Spring Boot 文件上传跨域问题的根源与解法，无论是本地调试还是生产环境，都能游刃有余地应对。

---