PSR-4自动加载失败的根本原因是命名空间与物理路径未严格对齐。配置时命名空间前缀须以双反斜杠结尾，路径为相对于composer.json的目录，子目录结构须与后续命名空间段一一对应，文件名须与类名一致且大小写敏感。
PSR-4 自动加载在 composer.json 中配置很简单，但写错路径、命名空间或目录结构会导致 Class not found 错误——根本原因往往是命名空间与物理路径不严格对齐，而不是“没生效”。
PSR-4 配置格式：键是命名空间前缀，值是相对路径
PSR-4 要求命名空间前缀（含结尾反斜杠）映射到一个目录，该目录下子目录结构必须与后续命名空间段一一对应。Composer 不会扫描整个目录，只按规则拼接路径。
-
"App\"必须以双反斜杠结尾（PHP 字符串中表示一个），否则解析为转义字符 - 路径值是相对于
composer.json所在目录的相对路径，不是绝对路径或相对于vendor/ - 路径末尾不加
/（如"src"✅，"src/"❌，后者可能在某些版本触发警告） - 多个命名空间可共用同一目录，但不能有前缀重叠（如同时配
"App\"和"App\Http\"会冲突）
{
"autoload": {
"psr-4": {
"App\": "src",
"Tests\": "tests"
}
}
}
类文件位置和命名必须严格匹配命名空间
PSR-4 不是“自动发现”，而是“确定性拼接”。给定 "AppUserRepository"，Composer 会尝试加载 src/User/Repository.php。任何偏差都会失败。
- 文件名必须与最末级类名一致（大小写敏感）：
src/User/Repository.php内必须是class Repository - 命名空间声明必须完整且结尾无多余
：namespace AppUserRepository;✅，namespace AppUserRepository;❌ - 目录分隔符统一用
/，即使在 Windows 上——Composer 内部自动转换 - 如果类在
src/User/Repository/DbRepository.php，命名空间应为AppUserRepository，类名为DbRepository
引入自定义类库时，别直接改 vendor 下的 autoload ——用 autoload-dev 或 paths
开发阶段想临时加载未打包的类库（比如本地调试的 SDK），不要手动编辑 vendor/autoload.php 或修改 vendor/composer/autoload_psr4.php，这些文件会在下次 composer install 时被覆盖。
- 用
"autoload-dev"配置仅开发环境生效的路径，适合测试类、桩类 - 若类库已发布为包但未上 Packagist，可用
"repositories"+"require"引入本地路径或 Git 仓库 - 极端情况需加载非标准结构（如扁平目录），可用
"files"数组直接 require 单个 PHP 文件（适合函数库）
{
"autoload-dev": {
"psr-4": {
"LocalTest\": "dev-tests/"
}
},
"repositories": [
{
"type": "path",
"url": "../my-private-sdk"
}
],
"require": {
"my-company/my-private-sdk": "*"
}
}
运行 dump-autoload 后仍找不到类？重点检查这三处
composer dump-autoload 只是重新生成映射表，不校验文件是否存在或命名是否合法。常见卡点不在命令本身，而在映射逻辑。
- 执行
composer show --paths查看 Composer 实际识别的根路径（确认src没被误判为不存在） - 用
composer dump-autoload -v看详细日志，它会打印“skipped”或“no files found”的提示 - 检查文件权限和扩展名：Linux 下
User.php和user.php是不同文件；Windows 下虽不区分，但 Composer 加载器默认只认.php
PSR-4 的严格性是它的优势，也是门槛——它不靠扫描猜路径，所以一旦配置好就极稳定；但配置错一行，就完全不工作，没有“差不多能用”的中间状态。
