在 composer.json 的 autoload 下配置 psr-4，键为带结尾反斜杠的命名空间前缀（如 "app\controllers\"），值为相对于 composer.json 的目录路径（如 "src/controllers/"），大小写和路径必须完全匹配。
composer.json 里怎么配 autoload 的 psr-4 命名空间
直接在 autoload 下写 psr-4 映射，Composer 就能自动加载你指定前缀的类。关键不是“定义命名空间”，而是告诉 Composer “这个命名空间前缀对应哪个目录”。
常见错误是把命名空间写成完整路径（比如 "App\Controllers\" 写成 "App/Controllers/"），或漏掉末尾的反斜杠——psr-4 要求键必须以 \ 结尾。
- 键必须是带结尾反斜杠的命名空间前缀，如
"App\Controllers\" - 值必须是相对于
composer.json所在目录的物理路径，如"src/Controllers/" - 路径支持相对写法，但不能以
/开头（即不能写绝对路径） - 多个映射可以并列，Composer 会按顺序尝试匹配
{
"autoload": {
"psr-4": {
"App\Controllers\": "src/Controllers/",
"App\Models\": "src/Models/",
"Tests\": "tests/"
}
}
}
为什么用 psr-4 而不是 classmap 或 files
psr-4 是动态映射，开发时增删类文件无需重生成 autoload；classmap 需要每次运行 composer dump-autoload 才能发现新类；files 只适合全局函数，不处理命名空间。
如果你只是想让某个工具类被自动载入，又不想加命名空间，files 更轻量；但只要涉及类 + 命名空间，psr-4 是唯一合理选择。
-
psr-4：类文件按命名空间结构组织，推荐用于绝大多数项目 -
classmap：适合遗留代码、无命名空间的老类，或需强制包含某些非标准路径 -
files：只加载指定 PHP 文件（如helpers.php），不走类加载机制
运行 composer dump-autoload 后还是找不到类
最常见原因是路径没对上：比如 "App\Services\" → "src/Services/"，但实际类文件放在 src/services/EmailService.php（小写 services）。Linux 系统区分大小写，路径错一个字母就失败。
- 检查文件系统路径是否与
composer.json中的值完全一致（包括大小写） - 确认类文件里的
namespace声明和psr-4键完全匹配（包括结尾\） - 执行
composer dump-autoload -o生成优化后的加载器，再用composer show --platform验证是否生效 - 临时加个
var_dump(get_included_files());在入口脚本里，看 autoload_files.php 是否被载入
vendor 目录外的自定义命名空间怎么热加载
如果代码不在项目根目录下（比如放在 ../shared-lib/），不能直接写相对路径到 psr-4，因为 Composer 不允许跨目录引用。正确做法是用符号链接或 repositories + path 类型包管理。
更轻量的方案是：在 autoload-dev 里加一条 psr-4，指向外部路径，并确保该路径在开发机上可访问；上线前必须移除或改用正式依赖方式。
- 不要在生产环境用
autoload-dev加载核心逻辑 - 符号链接方案需确保部署脚本同步创建，否则 CI 会失败
- 若外部库有自己
composer.json，优先用"type": "path"注册为本地包
命名空间本身只是 PHP 语法，真正起作用的是 Composer 怎么把它翻译成文件路径——这点容易被忽略，但恰恰是调试 autoload 问题的核心。
