PHPMailer 用 Composer 管理可解决类加载、版本冲突、TLS 协商、附件编码、HTML 样式丢失等问题；手动 require 易漏依赖、路径错、缺 openssl 扩展或 CharSet 设置，导致 SMTP 失败、中文乱码、图片红叉等。
PHPMailer 本身不依赖 Composer 才能用，但用 Composer 管理它确实能解决绝大多数“发送复杂邮件失败”的根源问题——比如类加载混乱、版本冲突、SSL/TLS 协商失败、附件编码错乱、HTML 内联样式丢失等。
为什么直接 require PHPMailer 文件会出问题？
手动下载 ZIP、复制 class.phpmailer.php 到项目里，看似简单，实则埋雷：
- PHPMailer 依赖
PHPMailer\PHPMailer\Exception和PHPMailer\PHPMailer\SMTP，缺一不可，手写require容易漏或路径错 - PHP 7.4+ 默认禁用
openssl扩展时，SMTP::startTLS()直接抛SMTP connect() failed，但错误信息不提示缺扩展 - 中文附件名用
addAttachment()时，没调用setLanguage()或没设对CharSet，收件端显示为乱码文件名 - HTML 邮件里带
<img src="cid:xxx" alt="如何解决发送复杂邮件的问题？使用Composer集成PHPMailer吧！" >，但忘了用addStringEmbeddedImage()绑定，图片就变成红叉
用 Composer 正确安装 PHPMailer 的关键步骤
不是 composer require phpmailer/phpmailer 一行完事。要控制行为和兼容性：
- 加
--with-all-dependencies：避免因旧项目已有symfony/polyfill-*导致安装中断 - 指定稳定版本：
composer require phpmailer/phpmailer:^6.9（别用^7.0，它强制要求 PHP 8.1+，很多生产环境仍是 7.4） - 确认
vendor/autoload.php被正确引入——不是放在include 'vendor/autoload.php';后就完事，要检查是否在脚本最顶部、无输出前执行 - 运行
php -m | grep openssl，确保 openssl 已启用；否则SMTP::enableDebug(true)会卡在STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT初始化阶段
发带附件+内嵌图+多语言正文的最小可靠代码
以下代码经实测在 Gmail、Outlook、Apple Mail 均可正常渲染，重点在参数顺序和编码设置：
立即学习“PHP免费学习笔记（深入）”；
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;
$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host = 'smtp.gmail.com';
$mail->Port = 587;
$mail->SMTPAuth = true;
$mail->Username = 'your@gmail.com';
$mail->Password = 'app-specific-password'; // 不是邮箱密码
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->CharSet = 'UTF-8'; // 必须设，否则中文主题/正文乱码
$mail->setLanguage('zh'); // 中文错误提示，非必需但调试友好
$mail->setFrom('your@gmail.com', '张三');
$mail->addAddress('user@example.com', '李四');
$mail->Subject = '订单确认：¥299.00';
$mail->isHTML(true);
$mail->Body = '<p>您好，您的订单已生成。</p><img src="cid:logo" alt="如何解决发送复杂邮件的问题？使用Composer集成PHPMailer吧！" >';
$mail->AltBody = '您好，您的订单已生成。';
// 内嵌图必须在 Body 之后、send() 之前添加
$mail->addStringEmbeddedImage(file_get_contents('logo.png'), 'logo', 'logo.png', 'base64', 'image/png');
// 附件注意：第三个参数是显示名，必须用 mb_encode_mimeheader() 处理中文
$filename = '发票_20240512.pdf';
$mail->addAttachment('/path/to/invoice.pdf', mb_encode_mimeheader($filename));
if (!$mail->send()) {
error_log('Mail error: ' . $mail->ErrorInfo);
}
最容易被忽略的 TLS 和 DNS 配置点
即使代码全对，仍可能发不出——问题常不在 PHP 层：
- Gmail SMTP 要求开启“两步验证”并生成“应用专用密码”，直接用邮箱密码会返回
SMTP Error: Could not authenticate. - 阿里云 ECS 默认屏蔽 25/465/587 端口，需在安全组手动放行 outbound 规则
- 自建 Postfix + PHPMailer 时，
Host写localhost不如写127.0.0.1，避免 IPv6 解析失败导致超时 -
SMTP::getServerExtList()返回空数组？说明 TLS 握手根本没完成，优先查 OpenSSL 版本和 CA 证书路径（openssl.cafile在 php.ini 中是否指向有效 bundle）
复杂邮件不是堆功能，而是每个环节都得稳：Composer 管版本、OpenSSL 管加密、DNS 管解析、SMTP 服务商管策略。少一个，send() 就可能静默失败或只发文本不发 HTML。
