Umbraco Forms v10配置表单发邮件工作流报SMTP断开错误

核心报错MailKit.Net.Smtp.SmtpProtocolException: The SMTP server has unexpectedly disconnected属于SMTP传输层连接被服务端主动中断，和Umbraco Forms表单提交逻辑无关——后台能正常看到提交记录，说明表单数据写入流程完全正常，问题集中在SMTP配置、网络连通性、Umbraco底层配置三个环节。

第一优先级排查：SMTP基础配置匹配问题 #

Umbraco 10开始替换底层邮件组件为MailKit，和老版本System.Net.Mail的自动适配逻辑不同，配置不匹配会直接被服务器断开，不会返回明确的语义化报错：

• 端口与加密模式必须严格对应
  • 用465端口时，加密模式必须选SSL/TLS (On Connect)，不能选STARTTLS。465是SMTP over SSL专用端口，发送STARTTLS协商指令会被服务端直接断开连接
  • 用587端口时，加密模式必须选STARTTLS，不能选直连SSL
  • 不要用25端口发公网邮件：国内云服务商默认封禁25端口外发流量，主流公网邮件服务商也已经淘汰25端口的明文传输
• 账号认证配置校验
  • 发件人邮箱地址必须和SMTP登录账号归属同个域名，绝大多数邮件服务商不允许冒用其他账号作为发件人，校验不通过会直接断连
  • 主流邮箱服务商（企业邮、网易、腾讯、Gmail等）要求使用独立SMTP授权码作为登录密码，不能直接用网页端登录密码，未生成授权码直接填登录密码会被认证拦截
• 网络连通性校验
  • 本地调试时检查防火墙、杀毒软件是否拦截对应SMTP端口的外发连接
  • 云服务器部署时先确认25端口是否需要申请解封，优先用465/587端口绕过默认封禁规则

第二优先级排查：Umbraco v10 底层SMTP配置 #

Umbraco后台的可视化SMTP配置存在配置优先级不生效的问题，必须直接核对根目录appsettings.json内的配置节点，正确配置格式如下：

"Umbraco": {
  "CMS": {
    "Global": {
      "Smtp": {
        "From": "发件人完整邮箱地址",
        "Host": "SMTP服务地址",
        "Port": 465,
        "SecureSocketOptions": "SslOnConnect",
        "Username": "SMTP认证账号",
        "Password": "SMTP授权码/密码",
        "DeliveryMethod": "Network"
      }
    }
  }
}

注意SecureSocketOptions字段不要留空、不要填Auto值：465端口固定填SslOnConnect，587端口固定填StartTls，Auto模式在部分SMTP服务上会出现握手失败。
配置完成后直接去Umbraco后台「设置-健康检查」运行SMTP连通性测试，健康检查会直接返回连接阶段的具体错误，不用等表单提交触发再查日志。

第三优先级排查：Forms工作流配置 #

• 无模板邮件工作流的收件人地址不要留空，不要填不存在的域名地址，部分SMTP服务校验收件人域名无效时会直接断连
• 工作流触发时机选「记录保存完成后」，不要选「提交处理中」，保存前触发可能出现上下文取值异常导致邮件组件初始化失败
• 需要定位具体断连阶段时，可以在appsettings.json中临时开启MailKit调试日志，复现问题后可以在日志里看到完整的SMTP握手流程：

"Logging": {
  "LogLevel": {
    "MailKit": "Debug",
    "MimeKit": "Debug"
  }
}

以上步骤覆盖了90%以上同类报错的场景，优先核对端口和加密模式的匹配关系，这是Umbraco 10升级MailKit后最高发的配置坑。

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