因为 Composer 自动加载基于类首次使用时单次 require，而 include_once/require_once 手动引入会破坏该机制，导致函数重定义、类重复加载等错误；尤其在框架已自动加载的前提下，人为干预极易引发重复包含。
为什么 include_once 和 require_once 在 Composer 自动加载中是反模式
Composer 的自动加载机制本身不依赖 include_once，它靠的是类名到文件路径的映射 + 单次 require。一旦你手动在代码里写 require_once 'vendor/autoload.php' 或在某个类里又 require_once 了已被 PSR-4 加载的文件，就可能触发重复包含——尤其是当框架（如 ThinkPHP、Laravel）已自动引入 autoload.php 时。
常见错误现象：Fatal error: Cannot redeclare function_xxx()、Class already exists、测试中函数突然不可用。
- 所有通过
autoload.files引入的 PHP 文件，Composer 默认用require_once加载，但仅执行一次 —— 前提是没被其他地方提前require或include -
psr-4和classmap类型的加载，底层是require，不是once；但因类只会在首次 new / use 时触发加载，天然避免重复 - 真正危险的是：你在控制器里手动
require_once 'app/helpers.php'，而它同时又被autoload.files管理 → 双重加载 → 函数重定义
autoload.files 中的辅助函数怎么防重复定义
全局函数无法像类那样靠命名空间隔离，autoload.files 是“无条件加载”，所以必须自己加守卫。
- 每个函数定义前加
if (!function_exists('my_helper')) { function my_helper() { ... } } - 不要在 helpers.php 里做有副作用的操作（比如
set_error_handler、define()常量），除非你确认每次请求都该执行一次 - 如果 helpers.php 依赖某个服务容器（如
app()），别把它放进autoload.files—— 因为文件在框架启动前就被加载，app()还未初始化 - 路径写错会导致
composer dump-autoload失败，但更隐蔽的问题是：路径存在但内容为空或只有注释，也会让 Composer 静默跳过，结果函数根本没加载
ThinkPHP/Laravel 项目里哪些地方最容易偷偷重复加载
框架封装了自动加载入口，但开发者常在不经意间绕过它。
- 在
config/或route/文件里直接require 'app/functions/global.php'—— 这些文件常被多次 include（如路由缓存重建时） - 第三方包自带
autoload.php并在composer.json里声明了files，而你又手动require了它的源码目录 - 使用
composer dump-autoload -o后没清 OPCache，旧的 classmap 缓存仍把废弃文件映射进来，导致看似“排除了”实则还在加载 - TP6 的
extend/目录若被误配进psr-4，又在业务代码里new extend\SomeClass()，而该类实际由另一个 autoloader 注册过（比如自定义 spl_autoload_register）
检查和验证是否真有重复包含
不能只看报错，得定位谁先加载、谁后加载、谁绕过了 Composer。
- 临时在疑似重复的文件开头加
echo "loaded: " . __FILE__ . "\n"; exit;，观察输出次数 - 运行
php -d opcache.enable=0 -r "require 'vendor/autoload.php'; var_dump(get_included_files());"，看 helpers.php 是否出现两次 - 用
debug_print_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS)在函数定义处打断点，查调用栈来源 - 在 CI 流程中加入校验：安装后执行
php -r "require 'vendor/autoload.php'; echo function_exists('my_helper') ? 'OK' : 'MISSING';"
Composer 的自动加载本身很干净，问题几乎全出在“人绕过它”的那一刻。最易被忽略的是：框架初始化前就执行的代码（如配置文件、早期中间件、CLI 命令入口）会脱离 autoload 控制范围，这时候任何手动 require 都可能成为重复源头。
