正确安装命令是composer require phpmailer/phpmailer；需注意PHP版本兼容性、SMTP配置差异、中文编码处理及服务器端口限制等问题。
composer install phpmailer 时提示 “package not found”
不是 phpmailer，也不是 php-mailer，官方包名是 phpmailer/phpmailer。很多人输错名字，直接搜“phpmailer composer”会跳进过时的镜像或废弃分支。
- 正确命令是：
composer require phpmailer/phpmailer - 如果项目锁定了 PHP 版本（比如
"php": "^7.4"），而你用的是 PHP 8.2，某些旧版phpmailer/phpmailer（如 v6.0 以下）会装不上——优先选^6.9或^7.0 - 别手动下载 ZIP 解压到
vendor/：Composer 不认，自动加载失效，new PHPMailer\PHPMailer\PHPMailer()会报Class not found
用 PHPMailer 发邮件时 connect() timeout 或 SMTP auth failed
绝大多数失败不是代码问题，而是 SMTP 配置和网络策略没对齐。Gmail、Outlook、腾讯企业邮箱的端口、加密方式、应用密码规则全都不一样。
- Gmail 必须开「两步验证」后生成「应用专用密码」，不能用账号密码；端口用
587+TLS，不是465+SSL - 腾讯企业邮箱（exmail）默认禁用 SMTP 外发，得在管理后台「邮箱设置 → SMTP 设置」里手动开启，并确认是否强制要求
SSL（有些版本只认465） -
$mail->isSMTP()必须在$mail->setFrom()之前调用，否则 SMTP 模式不生效，静默退化成 mail() 函数，发不出去还无报错
发送中文收件人或主题乱码 / 被当垃圾邮件
PHPMailer 默认编码是 UTF-8，但邮件头字段（To、Subject）必须做 MIME 编码，否则 Outlook、iPhone 邮件客户端直接显示问号或拒收。
- 收件人含中文？别直接写
$mail->addAddress('张三 <zhang>')</zhang>，拆成两参数：$mail->addAddress('zhang@example.com', '张三') - 主题含中文？用
$mail->CharSet = 'UTF-8'+$mail->Subject = '=?UTF-8?B?'.base64_encode('订单提醒').'?='，或者更稳的方式：交给 PHPMailer 自动处理——只要CharSet设对，调$mail->Subject = '订单提醒'即可 - 没设
$mail->isHTML(true)却在 Body 里写了<b>标签？会被当成纯文本，样式失效，且部分反垃圾系统扣分
本地开发能发，上线后失败（尤其宝塔、cPanel 环境）
不是 PHPMailer 的锅，是服务器层面拦截了出站 SMTP 连接。国内很多共享主机、轻量云默认封 25/465/587 端口，或限制 SMTP 调用频率。
立即学习“PHP免费学习笔记（深入）”；
- 先执行
telnet smtp.qq.com 587（或用nc -zv smtp.qq.com 587），看能否连通——连不通就不用试 PHPMailer 了 - 宝塔面板要进「安全」页放行对应端口，还要检查「PHP 设置 → 禁用函数」里有没有删掉
fsockopen、stream_socket_client - 某些环境禁用了
allow_url_fopen，导致 PHPMailer 内部加载证书失败（ca-bundle.crt读不到），可显式指定：$mail->SMTPOptions = ['ssl' => ['cafile' => '/etc/ssl/certs/ca-bundle.crt']]
