PHPMailer是PHP开发中常用的邮件发送类库，支持发送带附件的邮件，但在实际使用中经常会出现附件上传失败的情况，导致邮件无法正常携带附件发送。这类问题通常不是单一原因导致的，需要从代码配置、服务器环境、文件本身等多个维度排查。
常见失败原因及对应解决方案
1. 文件路径配置错误
PHPMailer添加附件时需要传入正确的文件绝对路径或相对路径，如果路径错误会直接导致附件添加失败。很多开发者容易混淆项目根目录的相对路径，或者使用了不存在的文件路径。
解决方法是先确认文件真实存在，再使用realpath()函数获取文件的绝对路径，避免相对路径带来的问题。
<?php
use PHPMailerPHPMailerPHPMailer;
use PHPMailerPHPMailerException;
require 'vendor/autoload.php';
$mail = new PHPMailer(true);
try {
// 服务器配置
$mail->isSMTP();
$mail->Host = 'smtp.ipipp.com';
$mail->SMTPAuth = true;
$mail->Username = 'test@ipipp.com';
$mail->Password = '邮箱密码';
$mail->SMTPSecure = 'tls';
$mail->Port = 587;
// 收件人设置
$mail->setFrom('test@ipipp.com', '发件人');
$mail->addAddress('receive@ipipp.com', '收件人');
// 添加附件，使用realpath获取绝对路径
$filePath = realpath('./uploads/test.pdf');
if ($filePath && file_exists($filePath)) {
$mail->addAttachment($filePath, '测试附件.pdf'); // 第二个参数是附件显示名称
} else {
echo '附件文件不存在，请检查路径';
}
$mail->isHTML(true);
$mail->Subject = '带附件的测试邮件';
$mail->Body = '这是一封带附件的测试邮件';
$mail->send();
echo '邮件发送成功';
} catch (Exception $e) {
echo '邮件发送失败，错误信息：' . $mail->ErrorInfo;
}
?>
2. 文件权限不足
如果附件文件没有读取权限，PHP进程无法读取文件内容，也会导致附件添加失败。这种情况在Linux服务器上比较常见，尤其是上传的文件默认权限设置过低时。
解决方法是检查文件的权限，确保运行PHP的用户（通常是www-data或nginx）有读取权限，可以通过chmod命令调整权限，或者使用is_readable()函数提前判断文件是否可读。
<?php
$filePath = './uploads/test.pdf';
// 判断文件是否可读
if (is_readable($filePath)) {
// 添加附件逻辑
} else {
echo '文件没有读取权限，请调整文件权限';
}
?>
3. 服务器上传大小限制
如果附件文件大小超过了PHP配置的上传限制，也会导致处理失败。需要检查php.ini中的两个配置项：upload_max_filesize和post_max_size，确保这两个值大于要发送的附件大小。
修改完成后需要重启PHP服务让配置生效，如果是共享服务器无法修改配置文件，可以联系服务商调整限制。
4. SMTP服务器限制
部分SMTP服务商对附件大小有额外限制，比如部分免费邮箱的附件大小不能超过10MB或者20MB，超过限制会导致附件上传失败。这种情况需要查看对应邮箱服务商的附件大小规则，或者压缩附件后再发送。
调试技巧
如果以上方法都无法解决问题，可以开启PHPMailer的调试模式，查看详细的SMTP交互日志，定位具体的错误原因。
<?php $mail = new PHPMailer(true); $mail->SMTPDebug = 2; // 开启调试模式，输出详细日志 $mail->Debugoutput = 'html'; // 调试信息输出格式 ?>
通过调试日志可以看到附件添加阶段、SMTP传输阶段的具体错误信息，从而更精准地定位问题根源。