Symfony 5.4使用Symfony Mailer配置Mailtrap发送邮件失败求助

按以下步骤逐一排查，绝大多数同类问题都可以快速定位解决：

1. 优先排除环境变量加载与缓存问题 #

Symfony不会实时读取.env文件的修改，改完配置第一时间执行清缓存命令，dev、prod环境都需要执行：

php bin/console cache:clear

另外注意检查配置覆盖问题：Symfony环境变量加载优先级为.env.local > .env.<环境名>.local > .env.<环境名> > .env，很多人在.env.local里留存了旧的MAILER_DSN配置，改根目录的.env完全不生效。执行以下命令可以直接校验当前系统实际加载的MAILER_DSN值：

php bin/console debug:container parameter=env(MAILER_DSN)

如果输出值和你配置的不一致，优先排查高优先级的env文件。

2. 修正MAILER_DSN配置格式 #

你当前注释掉的带参数的DSN才是可用配置，注意两个高频踩坑点：

• 不要把&写成HTML转义格式&，环境变量里直接写&即可，转义后会导致加密、认证模式参数无法被识别
• 不要省略加密配置，部分网络环境下无加密的SMTP连接会被运营商拦截
  直接替换为以下配置即可：

MAILER_DSN=smtp://d62b667a28d6af:023c577a51bb51@smtp.mailtrap.io:2525?encryption=tls&auth_mode=login

注意：Mailtrap每个收件箱的SMTP密码会定期自动重置，如果后续还是报认证错误，直接去对应收件箱的SMTP配置页复制最新的凭证，不要用旧密码。

3. 捕获具体报错定位根因 #

你当前的发信代码没有加异常捕获，看不到具体错误，临时修改代码加try-catch输出错误信息：

try {
    $this->emailVerifier->sendEmailConfirmation('app_verify_email', $user,
        (new TemplatedEmail())
            ->from(new Address('registration@my_host.com', 'Registration Confirmation'))
            ->to($user->getEmail())
            ->subject('Please Confirm your Email')
            ->htmlTemplate('registration/confirmation_email.html.twig')
    );
} catch (\Exception $e) {
    // 临时调试用，定位问题后删除即可
    dd($e->getMessage(), $e->getCode());
}

常见报错对应解决方案：

• 连接超时/连接被拒绝：本地或服务器出方向防火墙封禁了2525端口，先在命令行执行telnet smtp.mailtrap.io 2525测试连通性，不通就换端口（Mailtrap还支持25、465、587端口，对应调整DSN里的端口号即可）
• 认证失败：核对用户名密码是否正确，确认DSN里的特殊字符有没有做URL编码（如果密码里有@、:这类特殊字符，需要转义后写入DSN）
• 模板找不到：检查templates/registration/confirmation_email.html.twig文件是否存在，路径大小写是否和代码里写的一致

4. 校验mailer配置加载是否正确 #

你写的mailer.yml语法本身没有问题，要注意不同环境下的配置覆盖问题，检查config/packages/dev/、config/packages/prod/目录下有没有单独的mailer.yml文件覆盖了主配置。执行以下命令可以查看当前框架实际加载的mailer配置：

php bin/console debug:config framework mailer

确认输出的dsn值和你配置的MAILER_DSN一致即可。

5. 剥离业务逻辑做最小化测试 #

如果以上步骤都没找到问题，就绕过注册验证逻辑，单独写最小化发信代码测试SMTP连通性，排除verify-email-bundle或者业务逻辑的影响：
先创建测试命令：

php bin/console make:command test:send-mail

在生成的命令类里注入MailerInterface，写最简单的发信逻辑：

// 引入依赖类
use Symfony\Component\Mailer\MailerInterface;
use Symfony\Component\Mime\Email;
use Symfony\Component\Console\Command\Command;

// 在命令类里加构造函数注入Mailer
public function __construct(private MailerInterface $mailer)
{
    parent::__construct();
}

// 修改execute方法实现发信
public function execute(InputInterface $input, OutputInterface $output): int
{
    $this->mailer->send(
        (new Email())
            ->from('registration@my_host.com')
            ->to('your-test-mail@example.com')
            ->subject('Test Mail')
            ->text('This is a test email from Symfony')
    );
    $output->writeln('Test mail sent successfully');
    return Command::SUCCESS;
}

执行php bin/console test:send-mail，如果这个命令能发信成功，说明SMTP配置本身没有问题，故障点在verify-email-bundle的调用或者验证邮件模板渲染环节，优先排查模板传参、签名生成逻辑即可。

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