Java文件上传中文名变问号本质是服务端用ISO-8859-1错误解析UTF-8编码的filename参数;需前端正确编码、后端先按ISO-8859-1获取字节再用UTF-8重构文件名,同时配置CharacterEncodingFilter和Tomcat URIEncoding为UTF-8。

Java 文件上传时中文文件名变成问号(如 ???.pdf),本质是服务器端用 ISO-8859-1 解析了本应是 UTF-8 编码的文件名,导致字节被错误映射为不可见字符。核心不是“文件内容乱码”,而是 HTTP 头中 filename 参数的解码失败。解决需分两步:确保前端正确编码、后端正确解码。
确认并统一请求编码(服务端入口)
无论使用 Spring MVC、Servlet 还是 Apache Commons FileUpload,第一步必须让容器能正确读取原始请求体:
- 在 web.xml 中配置 CharacterEncodingFilter,filter 必须放在所有其他 filter 之前,且 encoding 显式设为 UTF-8
- 若用 Tomcat,检查
server.xml中 Connector 是否设置了URIEncoding="UTF-8"(影响 GET,但部分旧版 multipart 实现也会间接依赖) - Spring Boot 项目,在
application.properties加:server.servlet.encoding.charset=UTF-8server.servlet.encoding.force=true
正确解析 multipart 中的中文文件名(关键步骤)
标准 Servlet API(如 Part.getSubmittedFileName())或 Commons FileUpload 的 FileItem.getName() 返回的字符串,**在未做任何干预时,已按 ISO-8859-1 解码过一次**。此时直接用它,等于把 UTF-8 字节流当 ISO-8859-1 解,必然出错。正确做法是“反向还原”:
- 获取原始字节数组:
String rawName = part.getSubmittedFileName(); byte[] bytes = rawName.getBytes(StandardCharsets.ISO_8859_1); - 再以 UTF-8 重新构造:
String fileName = new String(bytes, StandardCharsets.UTF_8); - Spring MVC 用户注意:@RequestParam MultipartFile 的
getOriginalFilename()默认已尝试修复,但依赖容器配置;保险起见仍建议手动转码
避免常见陷阱
以下操作反而会加重问题,务必避开:
- 对已解码的字符串再执行
new String(name.getBytes("UTF-8"), "ISO-8859-1")—— 这是典型双解码,会导致二次乱码 - 在 Nginx 或反向代理层未设置
charset utf-8;,导致 header 被截断或重编码 - 前端用
FormData.append('file', file)时,未确保页面本身是 UTF-8() - 使用老版本 commons-fileupload(
补充:兼容老旧浏览器的下载头写法(顺带验证)
如果上传后还要提供下载,且需兼容 IE,可参考 Content-Disposition 的双格式写法,这反过来也印证了文件名编码逻辑:
- 现代浏览器:
Content-Disposition: attachment; filename*=UTF-8''%E4%BD%A0%E5%A5%BD.txt - IE 兼容:
Content-Disposition: attachment; filename="你好.txt"(HTML 实体)或filename="youhao.txt"(ASCII 文件名)
Java免费学习笔记:立即使用
解锁 Java 大师之旅:从入门到精通的终极指南











