安装 Symfony Mailer 只需执行 composer require symfony/mailer；关键问题在于 MAILER_DSN 格式错误、TLS/SSL 端口混用及 Gmail 发信被拒，需按 smtp://user:pass@host:port?encryption=tls&auth_mode=login 等规范配置。
Composer 安装 Symfony Mailer 不需要“精通”，只需要执行一条命令并配对一个环境变量或配置项；但多数人卡在 MAILER_DSN 格式写错、TLS/SSL 端口混用、或本地开发时用 Gmail 被拒发——这些才是真问题。
直接安装：只运行这一条命令
在已有 Symfony 项目（或纯 PHP 项目）根目录下执行：
composer require symfony/mailer
它会自动拉取 symfony/mailer 及其依赖（如 symfony/event-dispatcher、symfony/mime），无需手动 require 其他组件。如果你用的是 Symfony 6.2+，symfony/mailer 已预装，此时只需确认是否启用——检查 config/packages/mailer.yaml 是否存在且未被注释。
Mailer DSN 必须写对，否则 connect failed 或 timeout
MAILER_DSN 是 Symfony Mailer 的核心配置，格式为：transport://user:pass@host:port?options。常见错误包括：
- Gmail 使用
gmail://是过时写法，现在必须用smtp://+ OAuth2 或 App Password（开启两步验证后生成） - 端口和加密方式不匹配：比如用
smtp://user:pass@gmail.com:587却没加?encryption=tls，PHP 会默认走明文连接而被拒绝 - 腾讯企业邮箱或阿里云邮件推送，host 写成
smtp.exmail.qq.com却漏掉?auth_mode=login，导致认证失败
推荐本地开发用 smtp://null（丢弃模式）快速验证逻辑，生产环境再切真实 DSN：
MAILER_DSN=smtp://null
Symfony 项目中发邮件的最小可行代码
不用写完整服务类，先跑通发送逻辑：
$mailer = $container->get('mailer');
$email = (new \Symfony\Component\Mime\Email())
->from('hello@example.com')
->to('you@example.com')
->subject('Hi there!')
->text('A plain text message');
$mailer->send($email);
注意三点：
-
$container在控制器里可通过$this->container或构造注入MailerInterface获取，别硬写new Mailer() - 如果收件人是中文昵称，用
->to(new Address('you@example.com', '张三'))，否则可能乱码 - 发附件时，
addPart()要传RawContent或DataPart，不能直接传文件路径字符串
调试发信失败：看日志比看报错更有效
当 $mailer->send() 报 Connection could not be established with host 或静默失败，别急着改代码——先查日志：
- Symfony 开发环境：看
var/log/dev.log，搜索mailer或Failed to send email - 启用详细传输日志：在
MAILER_DSN后加&debug=true（仅开发环境），例如smtp://user:pass@smtp.gmail.com:587?encryption=tls&debug=true - 非 Symfony 项目需手动设置 Transport 日志处理器，否则异常堆栈里看不到 SMTP 对话细节
真正卡住的地方，往往不是 Composer 装没装上，而是 DNS 解析失败、防火墙拦截 587 端口、或者邮箱服务商把你的 IP 列入了临时限制名单——这些不会体现在 composer require 的输出里。
