class not found 根本原因是自动加载未触发或配置失效；最常见是入口文件漏引 vendor/autoload.php，导致 psr-4、classmap 等全部失效，后续所有配置均无效。
绝大多数 Class not found 报错，根本没触发 Composer 的自动加载逻辑——vendor/autoload.php 压根没被引入。
入口文件漏了 require vendor/autoload.php
这是最高频、最隐蔽的“假故障”。PHP 在找不到类时直接报错，不会提示“你忘了加载自动加载器”。只要入口文件（比如 index.php、test.php、artisan）第一行没写：
require __DIR__ . '/vendor/autoload.php';
后面所有 PSR-4 配置、dump-autoload、命名空间映射全白搭。检查点包括：
- 是否在 CLI 环境下运行却用了 Web 入口（或反之），导致加载了错误的入口文件
- 是否用了框架封装过的启动流程（如 Laravel 的
bootstrap/app.php），但自己写了新脚本却照抄漏了这句 - IDE 运行配置里工作目录设错，
__DIR__指向了非项目根目录，路径拼出来是错的
composer.json 的 psr-4 配置与实际类结构不匹配
PSR-4 不是“模糊匹配”，而是严格按命名空间前缀 + 目录结构做路径拼接。例如配置了：
"App\": "src/"
那么 AppHttpControllerUserController 就必须落在 src/Http/Controller/UserController.php。常见翻车点：
- 命名空间末尾少写双反斜杠：
"App": "src/"→ 应为"App\": "src/"（JSON 里要转义） - 类文件放在
app/而不是src/，但配置写的是"App\": "app/"却忘了改目录名 - 类名含下划线（如
My_Class），却硬套 PSR-4 ——它只认反斜杠分隔，下划线类得用classmap或已废弃的 PSR-0 - 大小写不一致：文件是
Usercontroller.php，但use AppHttpUserController;中 C 大写了
没运行 composer dump-autoload 或用了 --no-dev 导致映射失效
修改 composer.json 或增删类文件后，Composer 不会自动更新映射表。必须手动执行：
Workflow Decomposer
下载
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
composer dump-autoload
更推荐加优化参数（尤其上线前）：
composer dump-autoload -o
另外注意 CI/CD 场景：
-
composer install --no-dev会跳过autoload-dev区块，如果你把测试工具类写在tests/并配在autoload-dev里，生产环境就真找不到 - 本地开发时
composer update升级了某个包，其内部类结构变了，但你没重新dump-autoload，旧映射还指向已删除的路径
想绕过路径/命名空间约束？换 classmap
当目录杂乱、历史代码多下划线命名、或临时快速验证时，classmap 是最稳的兜底方案：
"autoload": {
"classmap": ["src/", "lib/", "LegacyUtils.php"]
}
它不看命名空间，只扫描指定路径下所有 .php 文件并记录 class => file 映射。但要注意：
- 新增类后必须再跑一次
composer dump-autoload，否则静默不生效 - 路径写错不会报错，只是对应类永远进不了映射表 —— 你看到的
Class not found仍是 PHP 原生错误，Composer 早已退出流程 - 生成的
autoload_classmap.php体积比 PSR-4 映射大，但对现代 PHP 性能影响可忽略
真正卡住人的往往不是 PSR-4 规则多难懂，而是错误发生在加载器启动之前——连映射表都还没读，你就已经在报错了。
