Composer PSR-4 自动加载严格依赖 composer.json 中 autoload 配置与文件路径、命名空间、类名三者完全一致，错一个层级或大小写即失效，必须执行 composer dump-autoload 生效。
Composer 的 PSR-4 自动加载不是靠“配置完就自动生效”，而是依赖 composer.json 中的 "autoload" 映射是否与实际文件路径、命名空间声明严格一致——错一个层级或大小写，composer dump-autoload 也救不回来。
PSR-4 映射必须满足三个硬性条件
PSR-4 不是“模糊匹配”，它对命名空间前缀、目录路径、类名拼写三者有确定性规则：
-
namespace声明必须以映射前缀开头，且剩余部分（去掉前缀后）要能一对一转为子目录 + 文件名 - 映射的目录路径必须是相对于项目根目录的**真实可读路径**（不能是软链未解析路径，不能拼错大小写）
- 类文件名必须严格等于类名 +
.php（如 classUserService→UserService.php），且文件内class名称与文件名完全一致
composer.json 中 autoload 配置写法与常见错误
正确写法示例（项目根目录下有 src/ 目录，对应命名空间 App\）：
{
"autoload": {
"psr-4": {
"App\\": "src/"
}
}
}
⚠️ 容易出错的地方：
- Windows 下写成
"App\\": "src\\"——src/结尾斜杠不能省，但反斜杠\在 JSON 中需双写，推荐统一用正斜杠 - 命名空间末尾漏掉反斜杠：
"App"❌ → 必须写成"App\\"（PHP 命名空间字符串中反斜杠是转义符，JSON 里要表示字面量\就得写\\） - 路径指向不存在目录，比如写成
"src/Utils/"但实际只有src/utils/—— Linux/macOS 区分大小写，Composer 不会帮你纠错 - 把
"autoload"错写在"require"或"scripts"下，导致完全不生效
修改后必须执行 dump-autoload 才能更新加载逻辑
改完 composer.json 后，不会立即生效。必须运行：
composer dump-autoload
如果只是新增类文件而没改配置，可以加 -o 生成优化后的类映射（提升性能）：
composer dump-autoload -o
注意：
-
composer install或composer update会自动触发dump-autoload，但仅限首次安装或锁文件变更时；日常开发中改了 autoload 配置，仍需手动执行 - 若用 IDE（如 PHPStorm）提示“class not found”，先确认是否已运行
dump-autoload，而不是直接怀疑代码写错了 - 调试加载问题可用
composer show -p查看当前已注册的 PSR-4 映射，或临时加一句var_dump(composer\Autoload\ClassLoader::getRegisteredLoaders());
多个命名空间共存与 vendor 冲突处理
一个项目可同时定义多个 PSR-4 前缀，例如：
{
"autoload": {
"psr-4": {
"App\\": "src/",
"Tests\\": "tests/",
"Vendor\\Package\\": "packages/vendor-package/src/"
}
}
}
但要注意：
- 前缀不能重叠，比如
"App\\"和"App\\Http\\"同时存在会冲突，后者会被前者覆盖（PSR-4 匹配取最长前缀优先） - 第三方包的 PSR-4 映射由其自身
composer.json定义，你无法覆盖；若发现vendor/下某包类无法加载，先检查该包的autoload配置是否合法，再确认是否被composer update正确拉取 - 如果你在
src/下写了Vendor\Package\SomeClass，但又装了同名第三方包，PHP 会按ClassLoader注册顺序加载——通常你的本地映射在前，但一旦混淆命名空间，后期极难排查
最常被忽略的一点：PSR-4 映射只影响 autoload 阶段，不改变 use 语句的解析逻辑；写错 use App\Http\Controllers\UserController 却把文件放在 src/Controllers/UserController.php，那再怎么调配置也没用——路径、命名空间、use 语句、文件物理位置，四者必须咬死对齐。
