在Spring REST接口开发中，处理包含文件上传的Multipart表单时，中文参数出现乱码是常见的问题，该问题通常和Tomcat的默认编码、Spring的Multipart解析器配置相关，需要针对性调整多个环节的配置。
问题产生的常见原因
Multipart表单编码问题的核心原因是请求内容的编码格式和解析时使用的编码不一致，常见的触发场景有以下几种：
- Tomcat服务器默认对POST请求的编码处理为ISO-8859-1，没有显式配置UTF-8编码
- Spring的MultipartResolver没有设置默认编码为UTF-8，解析表单参数时使用默认编码
- 前端表单没有指定enctype和accept-charset属性，或者属性值配置错误
- 过滤器没有对请求进行编码预处理，导致原始请求编码不符合预期
对应的解决方法
1. 配置Tomcat服务器编码
如果是独立部署的Tomcat，需要修改conf目录下的server.xml文件，在Connector标签中添加URIEncoding和useBodyEncodingForURI属性：
<Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443"
URIEncoding="UTF-8"
useBodyEncodingForURI="true" />
如果是在Spring Boot内嵌的Tomcat环境中，可以通过配置类自定义Tomcat的连接器属性：
import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory;
import org.springframework.boot.web.servlet.server.ServletWebServerFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class TomcatConfig {
@Bean
public ServletWebServerFactory servletWebServerFactory() {
TomcatServletWebServerFactory factory = new TomcatServletWebServerFactory();
factory.addConnectorCustomizers(connector -> {
connector.setURIEncoding("UTF-8");
connector.setProperty("useBodyEncodingForURI", "true");
});
return factory;
}
}
2. 配置Spring的MultipartResolver
Spring处理Multipart请求需要配置MultipartResolver，这里以CommonsMultipartResolver为例，需要显式设置默认编码为UTF-8：
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.multipart.commons.CommonsMultipartResolver;
@Configuration
public class MultipartConfig {
@Bean
public CommonsMultipartResolver multipartResolver() {
CommonsMultipartResolver resolver = new CommonsMultipartResolver();
// 设置默认编码为UTF-8
resolver.setDefaultEncoding("UTF-8");
// 设置单个文件最大大小，单位字节，这里设置为10MB
resolver.setMaxUploadSizePerFile(10 * 1024 * 1024);
// 设置总上传文件最大大小
resolver.setMaxUploadSize(50 * 1024 * 1024);
return resolver;
}
}
如果是使用Spring Boot的默认Multipart配置，也可以直接在application.properties或者application.yml中添加配置：
# 设置Multipart默认编码 spring.servlet.multipart.enabled=true spring.servlet.multipart.default-encoding=UTF-8
3. 前端表单配置
前端提交Multipart表单时，需要正确设置表单的属性，避免编码传递错误：
<form action="/upload" method="post" enctype="multipart/form-data" accept-charset="UTF-8">
<input type="text" name="username" placeholder="请输入用户名">
<input type="file" name="file">
<button type="submit">提交</button>
</form>
4. 添加编码过滤器
为了进一步保障所有请求的编码一致，可以添加编码过滤器，在请求到达Controller之前统一处理编码：
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.filter.CharacterEncodingFilter;
@Configuration
public class FilterConfig {
@Bean
public FilterRegistrationBean<CharacterEncodingFilter> encodingFilter() {
FilterRegistrationBean<CharacterEncodingFilter> registrationBean = new FilterRegistrationBean<>();
CharacterEncodingFilter filter = new CharacterEncodingFilter();
filter.setEncoding("UTF-8");
// 强制设置请求和响应的编码
filter.setForceEncoding(true);
registrationBean.setFilter(filter);
registrationBean.addUrlPatterns("/*");
return registrationBean;
}
}
验证方法
完成上述配置后，可以编写一个简单的Spring REST接口进行测试：
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;
@RestController
public class UploadController {
@PostMapping("/upload")
public String upload(
@RequestParam("username") String username,
@RequestParam("file") MultipartFile file) {
System.out.println("接收到的用户名：" + username);
return "用户名：" + username + "，文件大小：" + file.getSize() + "字节";
}
}
提交表单后如果控制台能正常打印中文用户名，且没有乱码，说明编码问题已经解决。如果仍然存在乱码，可以按照上述配置顺序逐一排查，确认每个环节的配置都生效。
Spring_RESTMultipart表单编码Tomcat修改时间：2026-06-25 05:15:34