PhpWord报错Class 'PhpOffice\PhpWord\Settings' not found排查

• 本地环境运行正常的PhpWord项目，将reporte.php及相关文件上传到服务器后无法运行
• 已验证路径配置正确：在phpWord.php中添加exit();可正常访问该文件，Settings.php与phpWord.php处于完全相同的目录，但运行时仍提示找不到Settings.php
• 报错触发位置：reporte.php中声明$phpWord变量的代码行

autoload.php #

已知loadLibraries方法的标准写法应为$path.$class.('.php')，当前写法在本地可正常运行：

function loadLibraries($class){
    require_once "/var/www/firescon/public/librerias/PhpOffice/PhpWord/PhpWord.php";
}

spl_autoload_register("loadLibraries");

?>

其余报表生成逻辑共2000行，已确认该部分代码无问题，如需查看特定部分代码可单独提供。

reporte.php #

<?php
require "/var/www/firescon/public/librerias/autoload.php";

use \PhpOffice\PhpWord\PhpWord;

$phpWord = new PhpWord();

当前自定义自动加载逻辑写法错误：spl_autoload_register注册的加载函数，会在每次实例化未被加载的类时，将完整类名作为参数传入加载函数执行。你写的loadLibraries函数完全忽略传入的$class参数，无论加载什么类都固定只引入PhpWord.php文件。
当代码执行new PhpWord()时，第一次触发自动加载引入了PhpWord.php，但PhpWord类内部依赖同命名空间下的Settings类，此时会再次触发自动加载，而加载函数依旧只重复引入已经加载过的PhpWord.php，不会加载Settings.php，最终触发类找不到的报错。
本地能运行是因为本地环境大概率存在其他自动加载逻辑（比如全局安装的Composer自动加载、php.ini配置的自动加载路径、其他文件提前引入了相关依赖等），补上了缺失的类加载，服务器环境没有这些额外配置，所以报错。

不要写这种固定引入单文件的自动加载，两种修复方式可选：

1. 如果是通过Composer安装的PhpWord，直接删除自定义的autoload.php，在reporte.php中引入Composer生成的vendor目录下的autoload.php即可
2. 如果是手动下载的源码包，把自动加载函数改成按类名解析路径的标准写法，参考代码：

function loadLibraries($class){
    // 只处理PhpWord命名空间下的类，避免影响其他项目加载逻辑
    if (strpos($class, 'PhpOffice\\PhpWord\\') !== 0) {
        return;
    }
    // 解析类名对应文件路径
    $relativeClass = str_replace('PhpOffice\\PhpWord\\', '', $class);
    $filePath = "/var/www/firescon/public/librerias/PhpOffice/PhpWord/" . str_replace('\\', '/', $relativeClass) . ".php";
    if (file_exists($filePath)) {
        require_once $filePath;
    }
}
spl_autoload_register("loadLibraries");

修复后所有PhpWord命名空间下的依赖类（包括Settings、其他工具类）都会被正确加载，不会再出现文件找不到的报错。

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