Composer不自动处理类名冲突，仅按配置注册加载规则；同名类会导致PHP致命错误。需先验证autoload是否生效，再检查PSR-4前缀、classmap优先级及离线环境配置。
Composer 不会自动处理类名冲突，它只按配置注册加载规则；一旦两个包都声明了同名类（比如 AppHelper），PHP 在第二次尝试加载时直接报 Fatal error: Cannot declare class AppHelper —— 没有预警，不给重试机会。
确认是不是真冲突，还是 autoload 没生效
很多“类冲突”其实是 autoload 根本没加载成功，先排除这个低级但高频的问题：
- 检查入口文件是否真的
require了vendor/autoload.php，CLI 脚本里漏写这行很常见 - 用
file_exists(__DIR__ . '/vendor/autoload.php')手动验证路径，尤其注意 Web 环境下$_SERVER['DOCUMENT_ROOT']和脚本实际位置可能不一致 - 运行
composer dump-autoload -v，看输出里有没有扫到你的命名空间和文件；如果压根没出现，说明composer.json的autoload配置无效（比如缩进错、逗号漏、PSR-4 末尾少） - 删掉
vendor/composer/autoload_*.php后再跑dump-autoload，避免旧缓存干扰
PSR-4 命名空间撞车的典型表现和解法
最常见冲突来源：两个包都用了宽泛前缀，比如都配了 "App": "src/" 或 "": "src/"。Composer 会把它们全注册进 autoloader，运行即崩。
Workflow Decomposer
下载
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 检查冲突包的
composer.json，重点看autoload和autoload-dev字段是否用了全局映射（如""）或过宽前缀（如"App\"） - 你自己项目中，绝不要把多个第三方包的源码目录塞进同一个命名空间下——哪怕只是放
Helper.php - 优先推动包作者收紧前缀，例如从
"App\": "src/"改成"VendorNamePackage\": "src/" - 若无法推动上游修改，可在你项目的
composer.json中用exclude-from-classmap主动屏蔽冲突文件（注意：这只对classmap有效，对 PSR-4 无效）
classmap 和 PSR-4 混用时谁说了算？
classmap 查表是 autoload 流程的第一步，一旦命中就直接返回路径，完全跳过 PSR-4 推导。这意味着：
- 如果你在
classmap里手动加了"src/Helper.php"，那么new Helper()就走 classmap；而new AppHelper()仍走 PSR-4 —— 类名不匹配，不会混 - PSR-4 映射必须以反斜杠结尾：
"App\": "src/"✅，"App\": "src"❌（后者会导致类名解析多一层） -
classmap路径写相对路径（如"lib/"），不能写"./lib/"或绝对路径 - 执行
composer dump-autoload -o后，classmap生成完整列表，但 PSR-4 映射仍保留 fallback 行为
离线环境下的加载失败怎么查？
离线时 composer install 可能跳过 autoload 重建，导致 vendor/autoload.php 里没注册新类或路径变更后的类。
- 先确认是否真离线：运行
composer install --no-scripts --no-plugins强制重走安装流程 - 手动触发 autoload 重建：
composer dump-autoload --optimize（别加--classmap-authoritative，它会删掉 PSR-4 回退逻辑） - 检查
composer.json中autoload是否含本地路径（如"src/": ["src"]），离线时这些路径必须真实存在且未被.gitignore误删 - 离线时
vendor/composer/autoload_static.php可能被 OPcache 缓存旧版本，需清 OPcache 或重启 PHP 进程
真正棘手的不是“找不到类”，而是“找到了两个同名类却不知道哪个先加载”。这种冲突往往藏在依赖树深处，靠 composer show --tree 和 composer why-not 定位比硬改配置更可靠。别指望 Composer 自动选边站队，它只负责注册，PHP 才决定炸在哪一行。
