前言

在前后端分离架构下，文件上传是一个常见功能。但在 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 跨域失败的常见原因

Spring Boot 未正确配置 CORS。
Multipart 配置未允许跨域请求，导致请求体被拦截。
API 网关层（Nginx、Spring Cloud Gateway）未处理 CORS。
前端携带了 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 {@Overridepublic 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: 50MBmax-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- OPTIONSallowedHeaders: "*"allowCredentials: true

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

5. 实战排查思路

确认预检请求 OPTIONS 是否成功
- 使用浏览器开发者工具查看是否返回 200，且带有 Access-Control-Allow-Origin。
确认文件大小限制是否正确
- 检查 spring.servlet.multipart.max-file-size 是否过小。
检查 Cookie/Token 配置
- 如果前端设置了 credentials: include，后端必须配置 allowCredentials(true)，并且不能使用通配符 *。
检查网关与后端的配置是否冲突
- 在 Nginx 或 Spring Cloud Gateway 中配置时，避免和后端重复处理。