PSR- 4 映射路径错误会导致 autoload 失败，必须确保 value 指向命名空间根目录、路径与命名空间严格匹配、更具体的映射需前置，修改后须执行 composer dump-autoload 验证。
composer.json 里写错 psr-4 映射路径会直接 autoload 失败
PSR-4 不是“写对命名空间就行”，它严格依赖目录结构和映射关系。常见错误是把 "App": "src/" 写成 "App": "src/App/"，结果 new AppServiceUserService() 找不到文件——因为 Composer 会拼出 src/App/Service/UserService.php，而实际路径可能是 src/Service/UserService.php。
实操建议：
-
psr-4的 value（路径）必须指向命名空间的“根目录”，不是“命名空间前缀对应目录” - 路径末尾加不加
/都行，但别写成"App": "src/App"这种多套一层的结构 - 修改后必须运行
composer dump-autoload，否则缓存没更新，改了也白改 - 用
composer show -p可以看当前已注册的 PSR-4 映射，验证是否生效
类文件名和命名空间不匹配导致 Class not found
PSR-4 要求类名完全等于文件路径相对于 namespace root 的相对路径。比如 "App": "src/"，那么 AppHttpControllersHomeController 必须放在 src/Http/Controllers/HomeController.php，少一个目录、大小写错、文件名带下划线都会失败。
常见错误现象：
- Windows 下不报错（文件系统不区分大小写），Linux 部署后直接
Class 'AppHttpcontrollersHomeController' not found - 写了
class HomeController extends Controller，但文件叫homecontroller.php—— Composer 只认HomeController.php - 命名空间末尾多了
，比如"AppServices": "src/Services/"，会导致解析异常
多个 psr-4 映射冲突时 Composer 怎么找类
Composer 按 composer.json 中 psr-4 数组的顺序匹配，遇到第一个能覆盖该类命名空间的就停。比如：
"psr-4": {"App": "src/", "AppTests": "tests/"} 这时 AppTestsTestCase 实际会去 src/Tests/TestCase.php 找——因为 "App" 更宽泛，先命中了。
正确写法是把更具体的放前面：
"psr-4": {"AppTests": "tests/", "App": "src/"}否则测试类永远加载不到，还查不出原因。
想加载非 PSR-4 的老代码？用 files 或 classmap
PSR-4 只处理符合规范的类，如果有些工具函数文件（如 helpers.php）或单文件类，不能靠命名空间自动加载，得手动注册。
推荐方式：
- 全局函数：加到
"autoload": {"files": ["src/helpers.php"]}，每次请求都 include - 零散类文件：用
"classmap": ["legacy/"]，Composer 会扫描目录下所有.php并建立类名→路径映射（不依赖命名空间） - 注意：改了
files或classmap后同样要composer dump-autoload
别试图用 PSR-4 去“凑”这些文件，路径和命名空间对不上，只会增加排查成本。
