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，运行即崩。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 重点检查所有依赖包的
composer.json，用grep -r '"psr-4"' vendor/找出谁在宽泛映射 - 特别警惕
""（空字符串）作为命名空间前缀的写法，它等于把整个src/目录平铺进全局空间 -
composer dump-autoload -o后生成的vendor/composer/autoload_psr4.php是最终映射表，可直接打开看哪条被留了下来——后加载的会覆盖前一个 - 优先推动包作者收紧前缀，例如从
"App\": "src/"改成"VendorName\Package\": "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 自动 resolve 冲突，dump-autoload 会按 composer.json 里 require 的顺序合并映射，后加载的包可能覆盖先加载的同名类。
- 用
composer show --tree（需提前在线运行并保存输出）比对依赖树，确认冲突来源是直接require还是 transitive 依赖 - 在
autoload段显式排除冲突路径："exclude-from-classmap": ["vendor/bad/pkg/src/ConflictClass.php"] - 若必须共存，改用
files方式加载关键类："autoload": {"files": ["vendor/good/pkg/helpers.php"]}，绕过classmap冲突 - 离线时
vendor/composer/autoload_static.php可能被 OPcache 缓存旧版本，重启 PHP-FPM 或调用opcache_reset()验证
真正难处理的不是“怎么屏蔽”，而是“哪个类该由谁负责”——当多个包都暴露了 CacheInterface 或 HttpClient 这类通用契约时，命名空间隔离只是起点，后续的接口适配、运行时封装、甚至 DI 容器绑定策略，才是真正决定系统能否长期稳定的关键点。
