Composer自动加载依赖显式注册的spl_autoload_register回调和预生成的映射表；require vendor/autoload.php必须首行执行以注册加载器，否则类实例化时因autoload队列为空而报Class not found。
Composer 自动加载不是“PHP 自己猜路径”，而是靠你写死的映射表 + 显式注册的 spl_autoload_register 回调共同生效；漏掉 require vendor/autoload.php 或没跑 composer dump-autoload，类就一定找不到。
为什么 require 'vendor/autoload.php' 必须放在第一行
这行代码不干别的，只做一件事：调用 ClassLoader::getLoader()，把 PSR-4、classmap、files 三类加载逻辑通过 spl_autoload_register() 挂进 PHP 的自动加载队列。一旦你在它前面写了 new AppController()，PHP 就会立刻触发 autoload 队列——但此时队列还是空的，直接抛 Class not found。
- 常见错误：入口文件里先 new 类、再 require autoload → 必定失败
- 更隐蔽的坑：框架启动前用了
set_include_path()或自定义__autoload()并返回false→ 后续 Composer 加载器被拦截 - CLI 脚本里漏掉这行却“偶然”跑通？大概率是其他依赖已提前加载过该类，别信这个假象
PSR-4 映射表从哪来、怎么拼出文件路径
映射数据不在 vendor/autoload.php 里，而在 vendor/composer/autoload_psr4.php 这种生成文件中，内容就是一个 PHP 数组，比如：['App' => ['src/']]。每次执行 composer dump-autoload，Composer 就扫描 composer.json 中的 autoload.psr-4 字段，硬绑定命名空间前缀和路径。
- 命名空间必须以反斜杠结尾：
"App\"合法，"App"（无反斜杠）完全不匹配 - 路径末尾必须带斜杠：
"src/"正确，"src"会导致拼成srcController/Home.php而非src/Controller/Home.php - 类名
App\Controller\Home剥离前缀后得Controller\Home，再把\替换成/→Controller/Home.php，最后拼上src/→src/Controller/Home.php - 文件名必须与末级类名严格一致：
Home.php里只能定义class Home，写成class home或文件叫home.php，Linux 下直接失败
改了 composer.json 为什么还是 Class not found
根本原因：你改的是配置源，不是运行时数据。vendor/autoload.php 只是启动器，真正干活的是它加载的 autoload_psr4.php 等静态映射文件——它们不会监听变化，只在 composer dump-autoload 时重写。
- 漏掉
require 'vendor/autoload.php'→ 整个链没注册，连加载器都没启动 - 改了
composer.json但没运行composer dump-autoload→ 映射表还是旧的，PHP 查表查不到新类 - 手动改过
vendor/composer/autoload_psr4.php→ 下次dump-autoload直接覆盖，白干 - CI/CD 流水线用了
--no-scripts→autoload_psr4.php根本没生成，检查vendor/composer/下是否存在该文件
classmap 和 PSR-4 混用时优先级与陷阱
两者共存时，ClassLoader 内部逻辑是：先查 PSR-4 前缀匹配，没命中再 fallback 到 classmap 全局查表。哪怕一个类既符合 PSR-4 规则又被扫进 classmap，PSR-4 仍优先生效。
- classmap 是暴力扫描型：配置写
"lib/"，Composer 就递归扫所有.php文件，用正则提取class/interface/trait名并记录绝对路径 - 代价明显：构建慢、更新不及时——类文件移动或删除后，不重新跑
composer dump-autoload，classmap 里还留着旧路径，容易加载错文件 - PSR-4 更轻量、可预测；classmap 适合非标准结构的老项目，新项目别滥用
最常被忽略的点：PSR-4 的反斜杠和斜杠不是“格式美观需要”，而是路径拼接的锚点；少一个、多一个，拼出来的就是完全不同的路径。Linux 下大小写敏感更是直接让 UserController.php 和 usercontroller.php 成为两个世界。这些约束不是 Composer 故意设障，而是机制本身决定的刚性边界。
