PHP脚本未检索全局includes目录无法加载PHPMailer问题咨询

该问题不属于Apache配置错误，也无需在vhost中单独添加参数，本质是PHP SAPI的include_path加载规则与代码引入写法不匹配导致的。

1. 先确认全局PHPMailer部署路径合规 #

Ubuntu 22.04下通过apt源安装的php-mailer默认存放路径为/usr/share/php/phpmailer，先执行命令确认文件存在：

ls /usr/share/php/phpmailer

如果目录不存在，直接执行全局安装命令即可，无需手动拷贝文件：

sudo apt update && sudo apt install php8.1-mailer

2. 修正代码的依赖引入写法 #

如果代码里用带路径前缀的方式引入（比如require __DIR__ . '/PHPMailer.php'、require './PHPMailer.php'），PHP只会在脚本所在目录检索文件，不会触发全局include_path查找逻辑。
全局引入的正确写法不要加任何路径前缀，配合命名空间声明使用即可：

<?php
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;
use PHPMailer\PHPMailer\Exception;

// 无路径前缀，PHP自动遍历include_path指定目录检索
require 'PHPMailer.php';
require 'SMTP.php';
require 'Exception.php';

3. 强制校准Apache运行时的PHP include_path配置 #

Ubuntu下不同运行模式的PHP使用独立的php.ini配置文件，即使phpinfo测试页显示路径正常，也可能存在配置未覆盖到PHPMailer子目录的情况。直接编辑Apache模块模式对应的php.ini文件，路径为/etc/php/8.1/apache2/php.ini，找到include_path配置项修改为：

include_path = ".:/usr/share/php:/usr/share/php/phpmailer"

保存后重启Apache生效：

sudo systemctl restart apache2

注意：不建议在vhost中通过php_value设置include_path，后续如果切换PHP为FPM运行模式，该类配置会直接失效，修改对应SAPI的php.ini是兼容性最高的方案。

4. 有效性验证 #

直接在任意子目录下新建测试脚本，写入以下代码确认配置生效：

<?php
// 打印当前运行环境实际加载的include路径
var_dump(ini_get('include_path'));
// 验证是否能检索到全局PHPMailer文件
var_dump(stream_resolve_include_path('PHPMailer.php'));

如果第二行返回/usr/share/php/phpmailer/PHPMailer.php类的全局路径，说明配置正常，无需在每个业务子目录重复存放PHPMailer模块。

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