classmap适合静态类文件，仅扫描指定路径下class/interface/trait声明生成映射表；files直接require指定php文件，适用于函数库或引导文件；psr-4优先于classmap，同名类以psr-4匹配为准；修改autoload后必须运行composer dump-autoload生效。
classmap 自动加载：适合静态类文件，但别乱扫目录
classmap 是 Composer 扫描指定路径下所有 PHP 文件，提取其中的类名，生成一张“类名 → 文件路径”的映射表。它不依赖命名规范，也不解析 use 或 namespace，只认 class、interface、trait 这三类声明。
常见错误现象：
- 把整个
vendor/或node_modules/加进classmap，导致composer dump-autoload极慢甚至卡死 - 放了带语法错误的 PHP 文件进去，
dump-autoload直接报ParseError中断
使用场景有限：主要用于遗留项目、无命名空间的工具类（比如 functions.php 里塞了 class Utils），或者你明确知道某些类不会改、想用最简方式加载。
实操建议：
- 只加具体目录或文件，例如
"classmap": ["src/legacy/", "lib/Helper.php"] - 避免嵌套过深或通配符，Composer 不支持 glob 模式
- 修改后必须运行
composer dump-autoload，否则新映射不会生效
files 自动加载：直接 require 那些“不能被类名定位”的文件
files 是最粗暴也最可靠的加载方式——Composer 会在每次自动加载初始化时，用 require 强制载入列表里的每个 PHP 文件。它不管里面有没有类，有没有命名空间，甚至可以是纯函数定义或常量声明。
常见错误现象：
- 把
bootstrap.php这类含副作用的文件放进files，结果在 CLI 和 Web 环境下重复执行（比如重复注册 error handler） - 路径写相对路径却没注意当前工作目录，导致
composer install时找不到文件
使用场景典型：
- 全局函数库（如
src/functions.php） - 配置引导文件（如
config/bootstrap.php） - 第三方不兼容 PSR-4 的小工具包
实操建议：
- 所有路径写相对于
composer.json的位置，不要用<strong>DIR</strong>或dirname(<strong>FILE</strong>) - 如果文件里有
return值，确保它不会干扰 autoload 流程（Composer 不关心返回值，但你的代码可能依赖它） - 它比
classmap更轻量，无需扫描，但无法按需加载——只要用了 autoload，这些文件就一定会被 require
PSR-4 和 classmap 混用时，优先级和冲突怎么算？
Composer 加载器按顺序尝试：先 PSR-4 / PSR-0，再 classmap，最后 files。但关键点在于：一旦某个类被 PSR-4 规则匹配到，就不会再查 classmap，哪怕 classmap 里真有这个类。
常见错误现象：
- 在
psr-4下写了"App\": "src/"，又在classmap里加了src/LegacyClass.php，结果new App\LegacyClass报错说找不到文件——因为 PSR-4 去找src/LegacyClass.php，而实际文件可能是src/legacy/LegacyClass.php - 同一个类名在两个不同路径下都存在，PSR-4 匹配成功就永远用它，
classmap里的同名类完全被忽略
实操建议：
- 不要让 PSR-4 规则覆盖
classmap的路径范围，比如"": "src/"这种空命名空间 + 全路径会彻底屏蔽 classmap - 如果必须共存，把
classmap的路径挪到 PSR-4 规则之外（例如放到legacy/目录，并不在 PSR-4 映射范围内） - 用
composer dump-autoload -o生成优化后加载器时，classmap会被合并进大数组，但 PSR-4 仍保持动态解析逻辑，这点不影响行为，只影响性能
为什么改了 composer.json 的 autoload 却没生效？
最常被忽略的是：Composer 不会在每次 require 时重新读取 composer.json，它只信任 vendor/autoload.php 和生成的 vendor/composer/autoload_*.php。
常见错误现象：
- 改完
classmap或files后直接跑脚本，发现新类还是找不到 - 本地测试正常，CI 上失败，因为 CI 没跑
dump-autoload，只跑了install
实操建议：
- 每次修改
autoload字段后，必须手动执行composer dump-autoload - 如果用了
-o或--optimize，记得加回去，否则 classmap 不会进优化文件 - 在 Git 里别忽略
vendor/composer/autoload_classmap.php—— 它不是生成物，是源码的一部分（虽然一般不用管）
有些项目把 autoload 当配置项随便改，却忘了这东西本质是一张静态快照，不是实时规则引擎。
