根本原因是自动加载未生效或命名空间错误；需确认composer require phpmailer/phpmailer、正确引入autoload.php、使用完整命名空间PHPMailerPHPMailerPHPMailer，并检查HELO域名可解析性。
composer install phpmailer 时提示 class not found
根本原因不是没装上，而是自动加载没生效。PHPMailer 的 autoload.php 不在 Composer 默认路径里，直接 require 'vendor/autoload.php' 后调用 PHPMailerPHPMailerPHPMailer 类，却报错说找不到类——大概率是命名空间写错了，或者没启用 Composer 的 PSR-4 自动加载。
- 确认安装命令是
composer require phpmailer/phpmailer（注意不是phpmailer单词拼错，也不是带下划线的旧包名） - 检查
vendor/composer/autoload_psr4.php是否包含'PHPMailer\PHPMailer\' => array($vendorDir . '/phpmailer/phpmailer/src') - 代码中必须用完整命名空间：
use PHPMailerPHPMailerPHPMailer;，不能只写use PHPMailer; - 如果手动 require
vendor/autoload.php，确保它在所有邮件相关代码之前执行，且路径没错（常见坑：../vendor/autoload.php相对路径出错）
配置 SMTP 发送失败：Connection failed
90% 的情况不是 PHPMailer 配置错，而是网络或服务端限制导致。比如本地开发环境连不上 Gmail 的 smtp.gmail.com:587，不是因为密码不对，而是因为没开「应用专用密码」，或开启了两步验证但没生成对应密钥。
- 先用 telnet 或
openssl s_client -connect smtp.gmail.com:587 -starttls smtp测试端口是否通（Linux/macOS）；Windows 可用Test-NetConnection smtp.gmail.com -Port 587 -
$mail->isSMTP()必须在$mail->setFrom()之前调用，否则 SMTP 模式不生效 - Gmail、Outlook 等要求开启「低安全性应用访问」已弃用，必须用「应用专用密码」+ 两步验证；国内企业邮箱（如腾讯企业邮）需确认是否启用 SMTP 服务、是否限制 IP 白名单
- 避免硬编码密码：把
$mail->Password = 'xxx';换成从环境变量读取，例如$_ENV['MAIL_PASSWORD']或用getenv('MAIL_PASSWORD')
中文乱码、附件无法打开、HTML 邮件显示为源码
这些不是编码设置漏了，而是关键属性顺序或值设反了。PHPMailer 对 CharSet、Encoding、isHTML() 的依赖很敏感，错一个就全崩。
-
$mail->CharSet = 'UTF-8';必须在$mail->Body和$mail->AltBody赋值前设置，否则中文主题/正文仍会乱码 - HTML 邮件必须显式调用
$mail->isHTML(true)，且$mail->Body是 HTML 字符串，$mail->AltBody是纯文本备用内容（否则 Outlook 可能只显示源码） - 添加附件用
$mail->addAttachment('/path/to/file.pdf', '发票.pdf');，第二个参数是显示名，含中文时无需 urlencode，PHPMailer 内部已处理 - 避免用
$mail->Encoding = 'base64';手动设编码——默认即可，改了反而可能让某些客户端解析失败
发信被当垃圾邮件：如何降低拒收率
不是加个 SPF 记录就完事。真实被拒主因是：发信域名和 From 域名不一致、没有 DKIM 签名、HELO 域名不可解析、内容触发关键词过滤。
立即学习“PHP免费学习笔记（深入）”；
- 确保
$mail->setFrom('no-reply@yourdomain.com', 'Your App')中的域名和你实际部署服务器的域名一致（不能用gmail.com做 From 却从自己 VPS 发） - HELO/EHLO 域名要可解析：用
$mail->Hostname = 'yourdomain.com';显式指定，否则 PHPMailer 默认用gethostname()，常返回内网名或不可解析主机名 - 测试工具比想象中重要：发一封到
check-auth@verifier.port25.com，它会回邮件告诉你 SPF/DKIM/DMARC 是否通过 - 别在正文中堆砌「免费」「限时」「点击领取」等营销词，哪怕只是测试也容易进 GMail 的 spam 文件夹
