React组件邮件模板预览与实际发送显示不一致问题求助

以下是导致这类问题的常见原因及排查要点：

1. 邮件客户端HTML/CSS兼容性限制 #

React组件在Preview.js（网页环境）中渲染的样式依赖现代网页标准，但Gmail等邮件客户端对HTML和CSS的支持有诸多限制：

• 几乎不支持flexbox、grid等现代布局方式，必须使用table布局实现复杂排版
• 仅支持内联CSS，<style>标签里的样式会被Gmail过滤，所有样式需直接写在元素的style属性中
• 部分CSS属性（如position: relative、margin:auto）无法正常生效，需用表格单元格的align、valign属性替代

2. Gmail API的邮件格式与编码问题 #

检查API路由中邮件内容的处理流程：

• 必须生成符合RFC 2822标准的邮件内容，需包含Content-Type头，明确指定text/html; charset=utf-8
• 邮件内容需进行URL安全的Base64编码（即base64url，而非普通Base64），Gmail API要求使用该编码格式
• 建议同时提供text/plain格式的备用内容，避免纯文本邮件客户端无法正常显示

3. React渲染的HTML结构问题 #

• 确保渲染后的HTML以<table>为核心布局容器，而非<div>为主的结构，邮件客户端对块状元素的排版支持极差
• 所有外部资源（图片、字体等）必须使用绝对URL，相对路径在邮件中无法被正确解析
• 检查是否存在未闭合的HTML标签，邮件客户端对语法错误的容错率远低于浏览器，标签不闭合会直接导致布局错乱

4. React渲染时机问题 #

如果是在客户端渲染HTML后再传给API路由，需确保组件已完成所有数据加载和渲染：

• 使用ReactDOMServer.renderToStaticMarkup()而非客户端渲染，生成完整的静态HTML内容，避免异步数据未加载完成导致的内容缺失
• 排查是否有组件依赖浏览器环境的API（如window、document），服务器端渲染时这些API不存在会导致渲染错误

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