升级javax.mail至1.6.2后非英文附件文件名编码异常求助

Hey there, let’s work through this filename encoding problem you’re hitting after upgrading JavaMail. To recap your situation clearly:

• Your app sends emails with attachments, and worked flawlessly on JavaMail 1.4 using MimeUtility.encodeWord(attachmentName, "UTF-8", null) for filename encoding
• After moving to 1.6.2, manual encoding caused garbled filenames like UTF-8_Q=E8=A1=A8=5FSUSAR=E7=A0=94=E7=A9=B6=E4=B8=AD
• Removing the manual encoding led to all non-English filenames showing up as question marks
• Setting System.setProperty("mail.mime.encodeparameters", "false") didn’t resolve the issue

Here are targeted fixes to try, tailored to JavaMail 1.6+ behavior:

1. Set Core MIME Charset Properties First #

JavaMail 1.6+ relies on system properties to handle charset defaults for headers (including filenames). Add these before initializing any JavaMail objects to enforce UTF-8 across the board:

System.setProperty("mail.mime.charset", "UTF-8");
System.setProperty("mail.mime.encodefilename", "true");
System.setProperty("mail.mime.decodefilename", "true");

These settings ensure all MIME-related text uses UTF-8, and force proper encoding/decoding of non-ASCII filenames.

2. Validate Your Filename String’s Charset #

Sometimes the root issue isn’t JavaMail, but the filename string itself being in the wrong charset. If your attachmentName comes from a file system, database, or external source, confirm it’s properly converted to UTF-8 before passing it to JavaMail:

// Example: If the filename was originally read in ISO-8859-1, convert it to UTF-8
String correctedFilename = new String(attachmentName.getBytes("ISO-8859-1"), "UTF-8");
mimeBodyPart.setFileName(correctedFilename);

3. Combine encodeparameters with Encoding Enforcement #

The mail.mime.encodeparameters=false setting disables modern RFC 2231 encoding (which some older clients struggle with) and falls back to legacy RFC 2047. But you need to pair it with a flag to ensure filenames are still encoded:

System.setProperty("mail.mime.encodeparameters", "false");
System.setProperty("mail.mime.encodefilename", "true");

This combination tells JavaMail to use the compatible legacy encoding method while still ensuring non-ASCII filenames aren’t dropped or turned into question marks.

4. Avoid Manual Header Modifications #

Make sure you’re not manually editing the Content-Disposition header for attachments. Let JavaMail handle this automatically when you call setFileName:

MimeBodyPart attachmentPart = new MimeBodyPart();
attachmentPart.setDataHandler(new DataHandler(new FileDataSource(attachmentFile)));
// Let JavaMail handle encoding—no need for manual MimeUtility calls
attachmentPart.setFileName(attachmentName);

Manually tweaking headers can override JavaMail’s built-in encoding logic and cause unexpected issues.

5. Test Across Different Mail Clients #

Sometimes the problem is client-specific. For example, older Outlook versions have known issues with RFC 2231 encoding, while modern clients like Gmail or Thunderbird handle it fine. Testing your emails in multiple clients can help confirm if the issue is with your code or client compatibility.

内容的提问来源于stack exchange，提问作者user01