Composer autoload 配置错误导致类找不到：PSR-4 命名空间前缀必须以 结尾（JSON 中写为 "App\"），classmap 路径须含 .php 且存在，修改后须运行 composer dump-autoload，加载优先级为 psr-4 → psr-0 → classmap → files。
autoload 配置里用错 psr-4 的命名空间前缀格式
先来看一个最典型的“坑”：Composer 可不会帮你自动补全那个小小的反斜杠。在配置 psr-4 时，命名空间前缀必须以 结尾，否则类文件就彻底“失联”了。举个例子，如果你在 composer.json 里写成 "App": "src/"，那可就错了，正确的写法应该是 "App\": "src/"（注意，这里的双反斜杠是 JSON 字符串转义后的表现，实际含义就是 App）。
一旦犯了这个错，你会看到什么现象呢？明明类 AppControllerHome 好好地躺在文件里，但执行 new AppControllerHome() 时，系统却无情地抛出一个 Class 'AppControllerHome' not found。
- 检查点：打开
composer.json，确认autoload.psr-4键值对的 key 是否包含了结尾的反斜杠（在 JSON 里要写成"App\"）。 - 验证方法：运行
composer dump-autoload -o后，去查看生成的vendor/composer/autoload_psr4.php文件，确认映射数组里是否包含类似'App\' => array(...)的条目。 - 特别注意：哪怕你的命名空间没有子级（比如就一个孤零零的
App），也必须老老实实写成"App\"，这个反斜杠绝对不能省。
classmap 扫描时忽略 .php 文件扩展名或路径拼写错误
接下来聊聊 classmap。这是一种静态扫描机制，不依赖文件名和类名的匹配规则，听起来很省心对吧？但它也有自己的“脾气”：它严格依赖你提供的路径是否真实存在、文件是否可读。只要路径写错、目录不存在，或者文件后缀忘了加 .php，那么 composer dump-autoload 就会直接忽略它们，不会将其加入最终的映射表。
常见的翻车现场是：你调用 MyHelper::doSomething() 时系统报错 Class not found，但你明明看到文件就躺在 lib/MyHelper.php 里。
- 路径规范：确保
autoload.classmap里列出的是相对于composer.json所在目录的路径，并且路径必须真实存在。写成"lib/MyHelper.php"✅ 是对的，写成"lib/MyHelper"❌ 就错了。 - 跨平台注意：在 Windows 系统下，如果把路径分隔符写成
可能导致扫描失败，最稳妥的做法是统一使用/。 - 强制刷新：运行
composer dump-autoload -a（强制重新扫描）后，检查vendor/composer/autoload_classmap.php文件，看看里面是否包含了对应的类名和完整路径。
开发中修改了 autoload 却没重新生成加载器
这一点看似简单，却最容易在忙碌的开发中被遗忘。Composer 的自动加载逻辑，完全依赖于 vendor/composer/ 目录下的那几个 PHP 映射文件。而这些文件，只在执行 composer dump-autoload 命令，或者进行依赖安装/更新时才会生成。换句话说，你改完了 composer.json 如果不执行这个命令，所有的改动都只是“纸上谈兵”，不会生效。
于是就会出现这种让人抓狂的情况：你反复核对配置，觉得天衣无缝，但新加的类就是加载不了；或者，你已经删除了某个旧类的路径，但它居然还能被实例化（这是缓存残留的“幽灵”）。
- 黄金法则：每次修改
composer.json中的autoload配置段之后，必须手动运行一次composer dump-autoload。 - 参数选择：加上
-o参数可以启用优化模式，生成扁平化的映射表，这对生产环境性能友好；在开发调试阶段，可以省略此参数，让加载过程更透明。 - 特殊情况：如果你之前用过
composer install --no-autoloader，或者手动删除过vendor/composer/autoload_*.php文件，那么仅仅运行composer install是不会重建这些加载器文件的，你必须显式地执行dump-autoload命令。
多个 autoload 类型共存时的优先级与覆盖行为
当项目里同时配置了多种自动加载规则时，情况会变得稍微复杂一些。Composer 会按照一个明确的顺序来尝试加载：psr-4 → psr-0 → classmap → files。这里有个关键点：对于同一个命名空间，如果 psr-4 和 classmap 的规则都能命中，那么 psr-4 拥有更高的优先级。这意味着，你可能满心以为用 classmap 覆盖了某个类，但实际上它根本没有被查找到的机会。
一个典型的场景是：你想替换某个第三方包里的一个工具类，于是用 classmap 指向了你的本地副本，结果运行时加载的却依然是原包里的版本。
- 查看规则：运行
composer show -s命令，可以查看当前所有生效的自动加载规则及其顺序。 - 配置策略：尽量避免对同一个命名空间混用
psr-4和classmap。如果确实需要覆盖某个包中的类，更推荐的做法是使用psr-4规则，显式地重新映射整个命名空间到你的自定义目录。 - 理解 files：
files类型比较特殊，它是通过直接require文件来工作的，没有命名空间的概念，通常用于加载全局函数库。它无法用于覆盖特定类。
最后，必须强调一个最常被忽略的核心原则：所有这些 autoload 配置规则，只影响 composer dump-autoload 命令所生成的映射文件。它们并不会改变 PHP 自身的 include_path，也不影响运行时的 require 行为。任何绕过 Composer 自动加载器、手动执行的 require 或 include，都不会受到这些配置的约束。理解这一点，才能从根本上把握自动加载的边界。
