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 碰运气。