Yii2高级版配置Swiftmailer（Gmail SMTP）报错求助

我之前在Yii2高级版里折腾Swiftmailer的时候踩过好几个坑，刚好和你的业务场景（访客提交姓名邮箱后发送带下载链接的邮件）匹配，咱们一步步来排查解决：

1. 先把Transport配置补全（最容易出错的点） #

你代码里transport部分是...，这部分是核心配置，不同邮箱服务商的SMTP参数差异很大，我给你几个常用的正确配置示例：

QQ邮箱配置 #

'transport' => [
    'class' => 'Swift_SmtpTransport',
    'host' => 'smtp.qq.com',
    'username' => 'your-qq@qq.com', // 你的QQ邮箱账号
    'password' => 'xxxxxx', // 这里是QQ邮箱的授权码，不是登录密码！
    'port' => 465,
    'encryption' => 'ssl',
],

163邮箱配置 #

'transport' => [
    'class' => 'Swift_SmtpTransport',
    'host' => 'smtp.163.com',
    'username' => 'your-163@163.com',
    'password' => 'xxxxxx', // 163邮箱的授权码
    'port' => 465,
    'encryption' => 'ssl',
],

划重点：一定要用邮箱的授权码，不是登录密码！授权码需要在邮箱后台开启POP3/SMTP服务后获取。

2. 检查依赖与运行环境 #

• 确认Swiftmailer扩展已安装：运行composer require yiisoft/yii2-swiftmailer，或者查看composer.json的require段有没有这个包。
• 检查PHP的openssl扩展是否开启：打开php.ini，找到extension=openssl，去掉前面的注释，重启Web服务器。
• 服务器防火墙是否放行SMTP端口：常用的465、587、25端口，需要确保服务器没拦截这些端口。

3. 配置与缓存的小细节 #

• 你已经设置useFileTransport => false，这个是对的，设为true的话邮件只会存到本地文件，不会真发送。
• 修改配置后一定要清Yii缓存：在项目根目录运行./yii cache/flush-all（Windows用yii.bat cache/flush-all），避免旧配置残留。
• 确认common/config/main-local.php被正确加载：高级版默认main.php会引入main-local.php，可以检查common/config/main.php里有没有类似return array_merge(require(__DIR__ . '/main-local.php'), [...]);的代码。

4. 业务代码的正确性（发送邮件部分） #

确保你在控制器里的邮件发送代码没有问题，比如：

// 假设$userName是提交的姓名，$userEmail是提交的邮箱，$downloadUrl是下载链接
Yii::$app->mailer->compose('@common/mail/ebook_download', [
    'userName' => $userName,
    'downloadUrl' => $downloadUrl,
])
->setFrom('your-email@example.com') // 这里要和transport里的username一致！
->setTo($userEmail)
->setSubject('您的电子书下载链接已生成')
->send();

同时要确保@common/mail/ebook_download.php模板文件存在，模板里要正确使用传递的变量：

<!-- common/mail/ebook_download.php -->
<h3>您好，<?= $userName ?>！</h3>
<p>点击下方链接下载您的电子书：</p>
<p><a href="<?= $downloadUrl ?>">立即下载</a></p>

5. 精准排查报错 #

如果还是报错，一定要看具体的错误信息：

• 如果是SMTP认证失败：检查授权码、用户名是否正确，加密方式和端口是否匹配服务商要求。
• 如果是无法连接SMTP服务器：检查主机地址、端口，以及服务器防火墙/安全组设置。
• 如果是模板找不到：确认viewPath路径正确，模板文件存在且权限正常。

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