FluentEmail 初始化失败主因是NuGet包安装错误，需安装FluentEmail.Smtp而非弃用的FluentEmail或空壳Core；SMTP配置须匹配端口与EnableSsl，用户名为完整邮箱并启用App Password；HTML邮件需显式声明UTF8编码及isHtml:true；异步发送必须全程await避免死锁。
FluentEmail 初始化失败：找不到 SmtpSender 类型
直接 new SmtpSender 报错“类型未找到”，多半是没装对 NuGet 包。FluentEmail 拆成了多个包，核心库 FluentEmail.Core 不含发送器，必须额外安装对应传输实现。只装 FluentEmail.Smtp 才能用 SMTP；如果要用 SendGrid，得换 FluentEmail.SendGrid。
推荐一步到位安装：
Install-Package FluentEmail.Smtp，它会自动拉取
FluentEmail.Core 依赖。别装 FluentEmail（老版本聚合包，已弃用），也别只装 Core——那只是个空壳，调 SendAsync() 时会直接抛 NullReferenceException。
SMTP 配置连不上：用户名、端口、SSL 设置三处易错
常见现象是 TimeoutException 或 “Authentication failed”。不是密码错了，而是 SMTP 服务端要求和客户端配置不匹配。
-
Port值必须和EnableSsl状态一致：Gmail/Outlook 用 587 +EnableSsl = true；部分企业邮件服务器用 465 +EnableSsl = true；绝不能配成 587 +false（多数服务商拒绝明文认证） - 用户名必须是完整邮箱地址（如
"user@gmail.com"），不是昵称或前缀 - Gmail 要开“App Password”，不能用主密码；Outlook 要在账户安全设置里启用“SMTP 授权”
初始化示例：
var sender = new SmtpSender(new SmtpClient
{
Host = "smtp.gmail.com",
Port = 587,
EnableSsl = true,
Credentials = new NetworkCredential("your@gmail.com", "app-password-here")
});
邮件内容乱码或样式丢失：HTML 渲染与编码没设对
发中文主题或 HTML 正文变成问号、CSS 不生效，问题出在两个地方：
-
Subject必须显式指定编码：email.Subject("你好", Encoding.UTF8)，否则默认 ASCII，中文全变 - HTML 模板里不能只靠
<meta charset="utf-8">，FluentEmail 默认 Content-Type 是text/plain。必须用.Body(htmlString, isHtml: true)显式声明 - 内联样式比外部 CSS 可靠；
<table> 布局比 Flex/Grid 兼容性好（尤其 Outlook） <p>正确写法：<pre class="brush:php;toolbar:false;">var email = Email .From("from@example.com") .To("to@example.com") .Subject("订单确认", Encoding.UTF8) .Body("<h2>您好</h2><p>订单已提交</p>", isHtml: true);</pre></p> <h3>异步发送卡死或超时：忘了 await 或线程上下文被截断</h3> <p>在 ASP.NET Core 控制器里直接写 <code>email.SendAsync().Result，会导致死锁——ASP.NET 的同步上下文会阻塞 awaiter 回调。这不是 FluentEmail 的 bug，是 .NET 任务调度机制的固有限制。必须保证调用链全程 async/await：
- 控制器 Action 标记为
async Task<iactionresult></iactionresult> - 调用
await email.SendAsync()，而不是.Result或.Wait() - 如果非要在同步方法里发（比如旧版 WinForms），改用
email.Send()（同步阻塞版），但注意会拖慢主线程
漏掉 await 的典型错误：
email.SendAsync(); // ❌ 忘了 await，任务被丢弃FluentEmail 本身轻量，但 SMTP 网络层、编码处理、模板解析这几块，任何一个环节配置偏移一点，都会导致静默失败或内容异常。重点盯住包引用、SMTP 参数组合、编码声明、async 流程这四点，基本能覆盖 90% 的实际问题。
- 控制器 Action 标记为
