1. 环境准备与依赖安装
1.1 PHP 与操作系统环境
在进行 PHPMailer 发邮件带附件的教程前，确保服务器具备稳定的 PHP 版本 7.2 及以上 或 PHP 8.x，以及一个可用的网络环境。此处也需要有一个 Web 服务器（如 Nginx/Apache）和一个数据库或静态文件目录用于测试。稳定的运行环境是成功发送附件邮件的前提。
1.2 Composer 依赖管理与 PHPMailer 安装
建议使用 Composer 来管理依赖，方便后续升级和打包。通过以下命令即可把 PHPMailer 引入到项目中，确保你有网络访问权限。PHPMailer 已在 Packagist 上维护，安装后可以通过自动加载加载类。
composer require phpmailer/phpmailer安装完成后，请在入口脚本中引入 自动加载器，以便直接使用 PHPMailer。下面示例展示常用的导入方式：vendor/autoload.php。
1.3 OpenSSL 与网络传输准备
发送 SMTP TLS/SSL 邮件通常需要 PHP 的 OpenSSL 扩展，以及服务器对外网络端口的开放。可通过以下命令快速检查或启用：extension=openssl 在 php.ini 中；并确保端口 465 或 587 对外可达。
# 检查 OpenSSL 模块是否加载
php -m | grep openssl# 如未加载，请编辑 php.ini 并重启 PHP-FPM/Apache
1.4 验证环境就绪
为了快速验证环境，创建一个简单的测试脚本，确保可以通过 PHPMailer 构造对象并进行基本配置。此步骤的目标是排除环境问题，确保后续的附件发送逻辑不会因环境引起失败。通过自动加载与命名空间即可快速开始调试。
2. PHPMailer 基本配置与邮箱参数
2.1 创建 PHPMailer 实例与 SMTP 设置
在邮件发送流程中，PHPMailer 实例化与 SMTP 传输配置是核心。通过设置主机、端口、加密以及认证信息，可以确保邮件通过你指定的 SMTP 服务发送。请将示例中的占位信息替换为实际凭据。
isSMTP();
$mail->Host = 'smtp.example.com';
$mail->SMTPAuth = true;
$mail->Username = 'user@example.com';
$mail->Password = 'yourpassword';
$mail->SMTPSecure = PHPMailer::ENCRYPTION_SMTPS;
$mail->Port = 465;
?>
2.2 指定发件人、收件人、主题与内容
设置发件人、收件人、邮件主题与内容是日常邮件的基础步骤。确保 发件人地址与你的 SMTP 授权账户匹配，否则可能被服务器拒收或标记为垃圾邮件。
setFrom('from@example.com', 'Your Name');
$mail->addAddress('to@example.com', 'Recipient Name');
$mail->Subject = '测试邮件 - PHPMailer 带附件';
$mail->Body = '这是一封测试邮件，用来验证带附件发送功能。';
?>
2.3 调试与错误输出配置
在开发阶段启用调试信息可以快速定位问题。将 SMTPDebug 设置为 2，并在发送失败时读取 ErrorInfo 字段获取错误详情。
SMTPDebug = 2; // 0 = off, 1 = client messages, 2 = client and server messages
?>
3. 为带附件发送邮件的实现
3.1 追加单个附件
核心逻辑之一是使用 addAttachment 来附加文件。你可以指定路径，或者同时自定义附件在收件端显示的名称。
addAttachment('/path/to/file.pdf'); // 如果需要，可以为附件自定义名称
?>
3.2 处理多个附件与命名
若要发送多份附件，重复调用 addAttachment 即可。也可以对每个附件设定不同的显示名称，提升邮件可读性。
addAttachment('/path/to/file1.pdf', 'Contract.pdf');
$mail->addAttachment('/path/to/image.jpg', 'ProductImage.jpg');
?>
3.3 附件校验与异常处理
在将文件添加到邮件前，先完成 路径校验与大小限制，避免发送失败。若发现附件不存在，应在逻辑中抛出异常或记录日志。
addAttachment($file);
} else {throw new RuntimeException("附件不存在: $file");
}
?>
3.4 带附件的完整发送示例
以下是一段整合了 SMTP 配置、收发、以及附件添加的完整片段，便于快速试验。请将占位信息替换为实际值。
isSMTP();
$mail->Host = 'smtp.example.com';
$mail->SMTPAuth = true;
$mail->Username = 'user@example.com';
$mail->Password = 'yourpassword';
$mail->SMTPSecure = PHPMailer::ENCRYPTION_SMTPS;
$mail->Port = 465;$mail->setFrom('from@example.com', 'Your Name');
$mail->addAddress('to@example.com', 'Recipient Name');
$mail->Subject = '带附件的示例邮件';
$mail->Body = '这是一个带附件的测试邮件。';
$mail->addAttachment('/path/to/file.pdf', 'Contract.pdf');
$mail->addAttachment('/path/to/image.jpg', 'ProductImage.jpg');try {$mail->send();echo '邮件发送成功';
} catch (Exception $e) {echo "邮件发送失败: {$mail->ErrorInfo}";
}
?>
4. 发送成功与调试技巧
4.1 发送成功的判断
检测 send() 的返回值和异常信息是判断邮件是否真正送达的关键。结合 try-catch 结构可以避免致命错误。
send()) {echo '邮件已发送';} else {echo '邮件发送返回值为 false';}
} catch (Exception $e) {echo "邮件发送失败: {$mail->ErrorInfo}";
}
?>
4.2 解决常见发送问题
遇到问题时，优先检查 SMTPHost、端口、加密方式和凭据是否正确，以及服务器对外网络是否可达。开启 SMTPDebug 可以看到服务器交互日志。
SMTPDebug = 2; // 查看服务器交互
?>
4.3 日志记录与安全要点
为了后续排错，请在发送后记录关键字段，如 ErrorInfo、SMTPError 等。并确保 凭据不要硬编码，应通过环境变量或秘钥管理服务注入。
Username = getenv('SMTP_USERNAME');
$mail->Password = getenv('SMTP_PASSWORD');
?>
