PSR-4 映射失败主因是命名空间与目录路径未严格对齐：需确保 composer.json 中命名空间以双反斜杠结尾、路径以斜杠结尾，文件名大小写匹配，且修改后运行 composer dump-autoload 验证 autoload_psr4.php 内容。
PSR-4 映射失败，90% 是因为 autoload 配置里路径没对齐命名空间层级，或文件结构没严格遵循“命名空间 = 目录路径”规则。
为什么 psr-4 映射总找不到类？
Composer 不会扫描整个目录，它只按 psr-4 里声明的前缀 + 命名空间后缀拼出相对路径，再拼上 vendor/autoload.php 的根目录（通常是项目根目录），最后检查该路径下是否存在对应文件。常见断点：
-
composer.json中的命名空间末尾漏了反斜杠\（如写成"App": "src/"而非"App\\": "src/"） -
src/下实际目录是src/App/Controller/，但类声明为namespace App\Controller;—— 这没问题；但如果写成namespace App\Controller\V1;，就必须存在src/App/Controller/V1/子目录 - 文件名大小写不匹配：Linux 下
User.php无法被new User()加载，若类名是User，文件必须叫User.php，不能是user.php
composer.json 里的 psr-4 怎么写才安全？
务必保证命名空间字符串以双反斜杠结尾，路径值以斜杠结尾（Composer 会自动处理路径分隔符，但显式加斜杠更可靠）。多个映射可共存，优先级按定义顺序，但建议避免重叠前缀。
{
"autoload": {
"psr-4": {
"App\\": "src/",
"Tests\\": "tests/",
"Vendor\\Package\\": "packages/vendor-package/src/"
}
}
}
-
"App\\": "src/"表示App\Foo\Bar类会查找src/Foo/Bar.php -
"Vendor\\Package\\": "packages/..."中命名空间带两级前缀，路径也需对应深度；若路径写成"packages/vendor-package/"，那Vendor\Package\Foo就会去找packages/vendor-package/Foo.php—— 错了，少了一层src/ - 修改后必须运行
composer dump-autoload，否则变更不生效
如何验证 PSR-4 映射是否生效？
别靠猜，用 Composer 自带命令看它到底怎么解析的：
composer show -p
输出中会列出所有已注册的 PSR-4 映射及其对应路径。更直接的办法是临时加个测试类，然后用 composer dump-autoload -o（优化模式）后，检查生成的 vendor/composer/autoload_psr4.php 文件内容 —— 里面就是最终生效的映射数组，一眼就能看出命名空间和路径是否对得上。
- 如果某个命名空间没出现在
autoload_psr4.php里，说明composer.json格式有误（比如忘了逗号、引号不闭合） - 如果出现了但路径不对，重点检查命名空间结尾的双反斜杠和路径结尾的斜杠
- Windows 用户注意：
autoload_psr4.php里路径用的是正斜杠/，不是反斜杠，这是 Composer 统一处理的结果，不用改
最常被忽略的一点：PSR-4 不支持通配符或模糊匹配，也不递归扫描子目录——它只根据命名空间字符串做一次精准路径拼接。哪怕你把所有类都扔进 src/ 根目录，只要命名空间是 App\Models\User，它就只会找 src/Models/User.php，不会去 src/User.php 碰运气。
