PHPMailer实例化报类未找到错误如何排查解决

故障表现 #

接手的遗留代码中，原本正常运行的PHPMailer集成业务本周突然停止工作。插入echo语句逐行调试时，代码执行到$mail = new PHPMailer(true);位置直接中断，后续输出语句不会执行。
初始调试代码如下：

<?php

echo '<p>First Debug line<br></p>';

use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;
use PHPMailer\PHPMailer\Exception;

echo '<p>after use<br></p>';

require 'vendor/autoload.php';

echo '<p>after vendor/autoload.php<br></p>';

$mail = new PHPMailer(true);

echo '<p>After PHPMailer<br></p>'; // 该语句始终无法执行

开启全量错误显示后，页面输出顺序为：First Debug line、after use、after vendor/autoload.php，随后抛出致命错误：

Fatal error: Uncaught Error: Class 'PHPMailer\PHPMailer\PHPMailer' not found in...

开启错误显示的调试代码如下：

<?php

ini_set('display_errors', '1');
ini_set('display_startup_errors', '1');
error_reporting(E_ALL);

echo '<p>First Debug line<br></p>';

use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;
use PHPMailer\PHPMailer\Exception;

echo '<p>after use<br></p>';

require 'vendor/autoload.php';

echo '<p>after vendor/autoload.php<br></p>';

$mail = new PHPMailer(true);

echo '<p>After PHPMailer<br></p>';

故障根因 #

use是PHP编译阶段处理的命名空间导入声明，不会触发实际的类加载逻辑，因此after use正常输出不代表PHPMailer类已经可用。
报错的核心原因是Composer自动加载器无法定位到PHPMailer的类文件，代码之前能正常运行、突然失效的常见触发场景：

• 近期执行composer install/composer update时进程中断，导致vendor目录下PHPMailer文件缺失、损坏
• 代码同步/部署操作漏传了vendor目录下的PHPMailer相关文件，或是composer.json、composer.lock被意外修改，PHPMailer被从依赖列表中移除
• Composer自动加载的类映射缓存过期，和实际文件路径不匹配

修复步骤 #

按顺序执行以下操作即可解决：

1. 打开项目根目录的composer.json，检查require配置项中是否存在phpmailer/phpmailer依赖，如果缺失直接执行composer require phpmailer/phpmailer重新安装依赖
2. 如果依赖配置正常，在项目根目录执行composer dump-autoload，重新生成完整的自动加载类映射
3. 上述操作无效时，直接删除项目下的vendor目录和composer.lock文件，重新执行composer install拉取全量完整依赖

注：如果调试文件不在项目根目录，需要调整vendor/autoload.php的引入路径为正确的相对路径，当前场景下autoload文件本身引入成功未报路径错误，该问题概率极低。

内容的提问来源于stack exchange，提问作者Egils Robs