Go go-smtp 怎样为已有 SMTP 服务建立 STARTTLS 连接

我在接入一套已有 SMTP 服务时，最容易写错的不是发信代码，而是把“587 端口上的 STARTTLS”和“465 端口上的隐式 TLS”混成同一种连接。使用 go-smtp 时，如果服务先接受普通 SMTP 会话，再通过 EHLO 宣布 STARTTLS，就用 smtp.DialStartTLS；如果手里已经有一条 net.Conn，则用 smtp.NewClientStartTLS。两者都会在认证前完成 TLS 升级。

官方地址：https://pkg.go.dev/github.com/emersion/go-smtp

最小做法是给 DialStartTLS 传入带 ServerName 的 tls.Config，连接成功后在同一个 Client 上调用 Auth 和 SendMail。不要用 InsecureSkipVerify 换取“能连上”。

先分清 STARTTLS 和隐式 TLS

STARTTLS 是“先建立 SMTP，再把当前连接升级到 TLS”。典型调用地址会带服务提供方分配的提交端口，例如 smtp.example.com:587。DialStartTLS 会连接服务器、完成 SMTP 初始交互并执行 STARTTLS，成功后才返回可继续使用的 *smtp.Client。

隐式 TLS 则从连接建立的第一字节就开始 TLS，常见入口是 465。go-smtp 对应的是 smtp.DialTLS，不能把它和 STARTTLS 的端口、时序互换。图中的箭头只用于帮助理解时序，是静态说明图，不是某个服务的运行截图。

准备带 ServerName 的 TLS 配置

服务端证书通常签发给 SMTP 主机名，因此 tls.Config.ServerName 应填写证书对应的主机名，而不是随手写成 IP 或账号域名。使用系统根证书时，通常不需要手工设置 RootCAs。

下面的配置把最低 TLS 版本写清楚，同时保留默认的证书和主机名校验。生产代码不要设置 InsecureSkipVerify: true；自签名证书应通过受控的根证书池解决。

tlsConfig := &tls.Config{
    // ServerName 用于证书主机名校验，也会参与 SMTP 服务端的 TLS 握手。
    ServerName: "smtp.example.com",
    // 只接受现代 TLS 版本，具体策略应与服务商支持范围一致。
    MinVersion: tls.VersionTLS12,
}

调用 DialStartTLS 建立客户端

有服务地址时，最小入口就是 smtp.DialStartTLS(addr, tlsConfig)。地址必须包含端口；如果端口写错，服务端可能没有 STARTTLS 能力，或者你会把隐式 TLS 端口当成普通 SMTP 端口。

我会先处理连接错误，再用 defer c.Close() 兜底释放资源。正常发信结束时再调用 Quit，让服务器收到 SMTP 的退出命令；如果中途认证或事务失败，关闭连接仍然是必要的清理动作。

client, err := smtp.DialStartTLS("smtp.example.com:587", tlsConfig)
if err != nil {
    // STARTTLS 不可用、证书不匹配或握手失败都在这里返回。
    return fmt.Errorf("connect SMTP with STARTTLS: %w", err)
}
defer client.Close()

// 成功返回的 client 已经完成 TLS 升级，可以继续认证和发信。
if _, ok := client.TLSConnectionState(); !ok {
    return errors.New("SMTP connection is not protected by TLS")
}

在加密连接上完成认证和发信

DialStartTLS 只负责连接和 TLS，账号认证仍要显式调用 Auth。认证成功后，可以用 Client 的 SendMail 发送一封 RFC 822 格式的消息；这个方法会复用已经建立的连接，不会再次启动 TLS。

我把 Quit 放在成功路径末尾，并在错误路径保留 Close 兜底。真实项目应从密钥管理系统读取密码，下面只使用占位变量。

package main

import (
    "crypto/tls"
    "errors"
    "fmt"
    "log"
    "strings"

    "github.com/emersion/go-sasl"
    "github.com/emersion/go-smtp"
)

func sendWithStartTLS(username, password string) error {
    tlsConfig := &tls.Config{
        // 主机名必须与 SMTP 证书匹配，不能为了绕过错误关闭校验。
        ServerName: "smtp.example.com",
        MinVersion: tls.VersionTLS12,
    }

    client, err := smtp.DialStartTLS("smtp.example.com:587", tlsConfig)
    if err != nil {
        // 连接、STARTTLS 命令或 TLS 握手失败时不继续发送账号信息。
        return fmt.Errorf("dial STARTTLS: %w", err)
    }
    defer client.Close()

    if _, ok := client.TLSConnectionState(); !ok {
        // 这是一个额外的状态保护，避免把未加密连接交给认证逻辑。
        return errors.New("TLS handshake did not complete")
    }

    auth := sasl.NewPlainClient("", username, password)
    if err := client.Auth(auth); err != nil {
        // 认证失败时直接返回，由 defer 负责关闭连接。
        return fmt.Errorf("SMTP auth: %w", err)
    }

    message := strings.NewReader(
        "From: sender@example.com\r\n" +
            "To: recipient@example.net\r\n" +
            "Subject: STARTTLS test\r\n" +
            "\r\n" +
            "This message is sent over an upgraded TLS session.\r\n",
    )
    if err := client.SendMail("sender@example.com", []string{"recipient@example.net"}, message); err != nil {
        // SendMail 失败时不要假设服务器已接受整封邮件。
        return fmt.Errorf("send SMTP message: %w", err)
    }

    // 正常结束时发送 QUIT；即使 QUIT 失败，连接也会由 defer 关闭。
    if err := client.Quit(); err != nil {
        return fmt.Errorf("quit SMTP session: %w", err)
    }
    return nil
}

func main() {
    // 示例只演示调用位置，凭据应来自环境变量或密钥管理系统。
    if err := sendWithStartTLS("user@example.com", "placeholder-password"); err != nil {
        log.Fatal(err)
    }
}

已有 net.Conn 和端口选择的边界

如果连接已经由上层拨号并拿到了 net.Conn，不要再调用 DialStartTLS 重新拨号，可以使用 smtp.NewClientStartTLS(conn, tlsConfig)。它会在这条已有连接上执行 STARTTLS，并返回一个新的 Client。

conn, err := net.Dial("tcp", "smtp.example.com:587")
if err != nil {
    // 自定义拨号失败时先结束，不要创建半初始化的 SMTP Client。
    return err
}
defer conn.Close()

client, err := smtp.NewClientStartTLS(conn, tlsConfig)
if err != nil {
    // STARTTLS 或 TLS 握手失败时，底层连接仍由调用方负责关闭。
    return fmt.Errorf("upgrade existing connection: %w", err)
}
defer client.Close()

还有三个容易混淆的边界：

• 服务不支持 STARTTLS：不要静默降级到明文认证；应记录错误并按业务策略终止或切换到明确支持的入口。
• 465 端口：如果服务商说明这是隐式 TLS，就使用 DialTLS，不要先按普通 SMTP 发送 EHLO。
• 旧教程使用 Client.StartTLS：当前 go-smtp 文档把它替换为 DialStartTLS 和 NewClientStartTLS，新代码直接采用公开的新入口。

常见问题

调用 SendMail 后还需要再次启用 TLS 吗？

不需要。只要 Client 是由 DialStartTLS 或 NewClientStartTLS 成功创建的，后续认证和发送都复用同一条已升级连接。

为什么证书校验会失败？

先检查 ServerName 是否与服务端证书匹配，再检查系统时间、根证书和服务商给出的主机名。不要把关闭证书校验当成修复方案。

go-smtp 的官方资料在哪里？

可以直接查看 https://pkg.go.dev/github.com/emersion/go-smtp，重点关注 DialStartTLS、NewClientStartTLS、DialTLS 和 Client.SendMail 的说明。

归纳起来：已有 SMTP 服务若采用“普通连接后升级”的模式，就用 DialStartTLS；已有底层连接则用 NewClientStartTLS；隐式 TLS 入口才用 DialTLS。把证书主机名、端口时序和 Client 生命周期分开处理，连接、认证和发信就不会互相混淆。