根本原因是手动重复引入 vendor/autoload.php，导致 Composer 自动加载器重复注册 PSR-4/ClassMap 映射，类被两次定义。常见于 phpunit.xml 与测试文件中同时加载、artisan 命令中二次 require 等场景。
为什么 require_once('vendor/autoload.php') 会报错“Cannot redeclare class”
根本原因不是 require_once 失效，而是你手动写了多次 require_once('vendor/autoload.php')，且其中至少一次发生在 Composer 自动加载机制已启动之后（比如在测试文件、命令行脚本或框架入口中重复引入）。Composer 的 autoload.php 本身内部就用 require_once 加载各类映射文件，但它的执行是一次性的；而你额外再调一次，会导致 PSR-4/ClassMap 映射被重复注册，最终在类首次被 autoload 触发时，PHP 尝试两次定义同一个类 —— 这才是 Fatal error: Cannot redeclare class 的真实来源。
- 常见错误场景：
phpunit测试里手动require_once 'vendor/autoload.php'，同时phpunit.xml又配置了bootstrap="vendor/autoload.php" - 另一个高频位置：Laravel 的
artisan命令或 Symfony Console 命令中，在__construct()或handle()里又补了一次require_once - 注意：
require_once对同一路径只生效一次，但它不阻止 Composer 内部 autoloader 的重复初始化逻辑 —— 这是很多人误以为“加了 once 就安全”的盲区
如何确认是不是 vendor/autoload.php 被重复加载
最直接的办法是加一句诊断输出，临时修改你的 vendor/autoload.php 文件顶部（仅调试用，勿提交）：
echo "[Autoload loaded at " . microtime(true) . "] ";
然后运行出错的命令（如 php artisan tinker 或 phpunit），看终端是否打印了两次以上该提示。如果出现两次，说明确实有外部代码主动触发了第二次加载。
- 不要依赖 IDE 的“跳转到定义”来判断 —— 很多 IDE 会误把 Composer 自动生成的
autoload_static.php当作入口 - 检查所有
php -f、exec()、shell_exec()调用，它们可能隐式拉起新 PHP 进程并再次加载 autoload - 某些部署脚本（如 Capistrano、Deployer）会在 post-deploy 阶段手动执行
composer install后又require，也容易触发
正确做法：只让 Composer 控制 autoload 初始化时机
绝大多数现代 PHP 项目根本不需要你手写 require_once('vendor/autoload.php') —— 框架、CLI 工具、测试套件都已内置 autoload 引导逻辑。你要做的是「删掉所有手动 require」，把控制权交还给生态。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- Laravel：入口
public/index.php和artisan文件里已有require __DIR__.'/../vendor/autoload.php';，其他地方禁止再写 - PHPUnit：删掉测试文件顶部的
require_once，确保phpunit.xml中<php><include path="vendor/autoload.php"/></php>或bootstrap属性指向它即可 - 纯脚本（如
scripts/deploy.php）：若需独立运行，用#!/usr/bin/env php开头，并在第一行后立刻require 'vendor/autoload.php';—— 且仅此一处 - 绝对避免在循环、条件分支、trait 或 __autoload 函数里动态 require autoload.php
真需要动态加载？用 Composer 提供的正式 API
极少数场景（如插件系统、运行时切换依赖版本）确实要干预 autoload，但绝不能硬 require。应使用 Composer 官方支持的方式：
$loader = require 'vendor/autoload.php';
// 后续可调用：
$loader->add('MyPlugin\', __DIR__ . '/plugins/myplugin/src/');
$loader->register(true); // true 表示 prepend，避免与主 autoload 冲突
这个 $loader 是 ComposerAutoloadClassLoader 实例，它允许安全地追加命名空间，不会破坏已有映射。
- 不要试图 new ClassLoader() 后自己 setPsr4 —— 缺少 Composer 生成的优化映射（如
autoload_classmap.php），性能差且易漏类 - 如果项目用了
composer dump-autoload --optimize，那autoload_files.php里的文件也会被预加载，手动 require 会直接导致重复声明 - 线上环境尤其要注意：有些 Dockerfile 在
RUN composer install后又执行COPY . . && php index.php，若 index.php 里有 require_once，就会撞上容器内已存在的 autoload 状态
真正麻烦的从来不是 require_once 写没写对，而是你不知道 autoload 机制在哪一层被谁悄悄启动了 —— 查日志、打时间戳、盯住进程生命周期，比背命令重要得多。
