“Cannot declare class”错误根源是PSR-4 autoload注册了冲突路径导致同名类被重复加载，常见于多个包配置相同命名空间前缀、手动引入与自动加载重叠或vendor符号链接异常；需用composer dump-autoload -vvv定位生效映射，并通过exclude-from-classmap（仅限classmap）或修改name/autoload同步解决。

为什么require vendor/autoload.php后报“Cannot declare class”

这不是 autoload 没生效，而是它加载了两个同名类——PHP 不允许重复声明，直接 Fatal error。错误信息里出现的中文提示（如“类已定义”）只是 PHP 错误翻译层的表现，根源在 autoload 规则注册了冲突路径。
常见触发点：

• 两个包都在 composer.json 中配置了相同的 PSR-4 前缀，比如都写了 "App\": "src/"
• 你手动 include 过某个 Helper.php，之后 Composer 又尝试加载同名类
• vendor 目录被符号链接挂载，导致 __DIR__ 在 vendor/autoload.php 里指向空路径，PSR-4 映射全部失效

验证是否真走对 autoload：在出错脚本开头加 var_dump(class_exists('SomeClass'));，返回 false 就说明根本没加载到正确类文件。

怎么快速定位是哪个包在注册冲突命名空间

别翻所有 composer.json，用 Composer 自带命令查：

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

• 运行 composer dump-autoload -vvv | grep -A5 -B5 "YourNamespace\"（把 YourNamespace\ 替成你要查的，注意结尾反斜杠要转义）
• 看输出里最后出现的那条映射，就是实际生效的路径
• 再用 composer show vendor/package-name 查具体包的 autoload 字段
• 或者全局扫：grep -r '"YourNamespace\\":' vendor/*/composer.json

PSR-4 冲突比 classmap 更隐蔽：classmap 扫描会报 warning，而 PSR-4 是静默覆盖——后注册的规则完全接管前一个，但 PHP 解析器只认第一次定义的类。

exclude-from-classmap 能屏蔽冲突类吗

能，但仅对 classmap 生效，对 PSR-4 无效。
适用场景：

• 某个包的 vendor/package/src/ 下混着旧版 stub 类或测试工具类，它们有合法命名空间但不该参与自动加载
• 你无法改包源码，又必须集成它，且冲突类只出现在 classmap 扫描范围内

配置写法（加在你项目的 composer.json）：

"autoload": {
    "exclude-from-classmap": ["vendor/conflict-pkg/src/DeprecatedHelper.php"]
}

改完必须执行 composer dump-autoload，否则不生效。注意：这不能解决 PSR-4 映射重叠问题，比如两个包都声明 "Monolog\": "src/"，就得改包的 autoload 配置或用 replace。

fork 包后类还是找不到？name 和 autoload 必须同步改

Composer 报 Package xxx is already registered，是因为 name 字段是唯一键——哪怕 URL 不同、代码不同，只要 name 一样就拒绝加载。
改 fork 包必须做三件事：

• 改 composer.json 的 name，例如从 "monolog/monolog" 改成 "acme/monolog"（别用 "monolog_custom" 这种易撞名的）
• 如果命名空间也改了（比如从 Monolog\ 改成 Acme\Monolog\），autoload 里的 PSR-4 前缀必须同步更新
• 主项目中用 repositories 指向新源，并在 require 里写新 name；若其他依赖仍引用原包，还得加 replace 声明替代关系

漏掉任何一步，都会导致类找不到或安装失败。最常被忽略的是：改了 name 不等于类就能自动加载，autoload 路径没对上，照样 Class not found。