SendGrid Java邮件模板正确处理前端换行符

很多团队在使用 SendGrid Java SDK 发送 HTML 邮件时，都会遇到一个挺常见的尴尬场景：前端用户通过 textarea 提交了一段多行文本，收到邮件后，内容全挤成了一行。换行符呢？浏览器早把它当空格合并了。

先说结论，核心问题就出在 HTML 的规范上。纯文本里的换行符，也就是 \n，在 HTML 中默认是不会被渲染成可视换行的。想让邮件内容里的段落真正分段，要么用
标签，要么借助 CSS 属性（比如 white-space: pre-wrap）。而后者因为没有对用户输入做转义，面对不可信数据时有 XSS 风险，通常不推荐。

那么，在 SendGrid 的 Java 环境里，应该怎么正确又安全地把换行符从文本变成邮件里的换行呢？

根本原因：HTML 对换行符的忽略

本质上，浏览器在渲染 HTML 时，只会把
标签当作换行指令。其他任何纯文本里的回车、换行符，都会被当作空白符并挤压成一个空格。前端提交的 \n 或 \r\n 自然也在其中。所以，问题就变成了：服务端该如何在拼接邮件模板时，把这些原始换行符“翻译”成浏览器能识别的换行标签。

推荐方案：服务端预处理 + 安全转义

最稳妥的做法，不是在模板里做文章，而是在 Java 服务端拿到用户输入的字符串后，先做一次 HTML 转义，再替换换行符。顺序非常关键，需要先转义，再换行。

import org.apache.commons.text.StringEscapeUtils;

public static String convertNewlinesToBr(String input) {
    if (input == null) return "";
    // 1. 先进行 HTML 转义（防止 XSS）
    String escaped = StringEscapeUtils.escapeHtml4(input);
    // 2. 将换行符替换为 
（注意：仅替换 \n，\r\n 已被标准化为 \n）
    return escaped.replace("\n", "
");
}

然后在构造 SendGrid 邮件内容时，直接拿处理后的字符串嵌入模板即可：

Email from = new Email("sender@example.com");
String subject = "Your Dynamic Email";
Email to = new Email("recipient@example.com");

// 假设 frontendText 来自 HTTP 请求体
String frontendText = request.getParameter("message");
String htmlSafeWithBr = convertNewlinesToBr(frontendText);

Content content = new Content("text/html", 
    "
Message:
" + htmlSafeWithBr + "
");
Mail mail = new Mail(from, subject, to, content);
// ... 发送逻辑（使用 SendGrid API client）

关键注意事项

• 顺序不可颠倒：必须先调用 StringEscapeUtils.escapeHtml4() 对用户输入做完整转义，再通过 replace 把换行符换成
。反过来搞，转义函数会把已经插入的
也给转义成纯文本，那样就白费功夫了。
• Java 里没有现成的 nl2br：PHP 提供的 nl2br() 函数在 Java 里并不存在。手动实现这一“转义加替换”的两步流程，是目前最安全、最可控的做法。
• CSS 备选方案（慎用）：在某些模板完全可控且数据绝对可信的极端场景下，可以对目标容器设置 style="white-space: pre-wrap;"，这样不需要替换字符串，也能保留原始格式。不过还是那句话，这个方案要求“完全可信数据”，普通业务场景下强烈不推荐。

{{unescaped_user_input}}

总结

在 SendGrid Java SDK 中安全呈现用户多行文本的核心，就是“先转义，后换行”。通过 StringEscapeUtils.escapeHtml4() 防御 XSS 攻击，再用 replace("\n", "
") 实现语义化换行，即可在 HTML 邮件中稳定、安全地展示出用户输入的真实段落结构。