Composer类库映射必须严格遵循PSR-4规则，命名空间与目录结构精准对齐，否则自动加载退化为全量扫描，显著降低性能；错误配置如路径大小写不一致、缺失末尾反斜杠或未加-o优化，均会导致O(1)查找变为O(n)遍历。
Composer 的类库映射不是“配了就快”，而是必须按 PSR-4 规则精准对齐命名空间与目录结构，否则自动加载器会退化为全量扫描 vendor/autoload.php 中的 files 列表或兜底的 classmap，反而更慢。
PSR-4 映射写错，autoload 就变 full-scan
常见错误是把命名空间前缀和物理路径搞混，比如在 composer.json 里写：
{
"autoload": {
"psr-4": {
"App\": "src/"
}
}
}
这本身没问题——但一旦你实际代码里定义了 namespace AppHttpControllers;，而文件却放在 src/controllers/（小写、无嵌套），composer dump-autoload 不报错，但运行时 AppHttpControllersLoginController 找不到，Autoloader 只能 fallback 到遍历所有 classmap 条目或逐个 require files，I/O 次数暴增。
- 命名空间末尾的
\必须存在，漏掉就变成前缀匹配，可能意外命中其他包 - 路径必须以
/结尾（Windows 下也用正斜杠），否则 Composer 会拼接出错误路径 - 修改后务必执行
composer dump-autoload -o，不加-o不生成优化后的classmap，PSR-4 规则不会生效
何时该用 classmap 而非 PSR-4
PSR-4 依赖文件系统实时解析路径，适合标准命名结构；classmap 是静态索引，适合以下场景：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 遗留代码没遵循命名空间规范，比如全局函数文件
helpers.php或functions.php - 动态生成的类（如模板编译产出的
__TwigTemplate_*.php） - 第三方未提供 autoload 配置的老包，又不想 fork 修改
配置方式直接列文件或目录：
{
"autoload": {
"classmap": ["src/helpers.php", "legacy/"]
}
}
注意：classmap 生成后是固定快照，新增文件必须重新运行 composer dump-autoload，否则不生效。
vendor 目录外的类怎么进自动加载
项目根目录下放的 app/ 或 core/ 这类自定义目录，不能靠默认 vendor autoload 覆盖。必须显式加入主项目的 autoload 配置：
- 如果目录内是标准 PSR-4 结构，加到
"psr-4"下，例如"Core\": "core/" - 如果是混合风格（含函数+类+接口），优先走
"classmap"，避免路径推导失败 - 切勿在
vendor/composer/autoload_*.php里手动改代码——下次composer update全被覆盖
真正影响寻址耗时的，从来不是“有没有配 autoload”，而是“配得准不准、退不退化”。一个错位的斜杠、一次忘记 -o 的 dump，都可能让本该 O(1) 的命名空间查找，变成 O(n) 的文件遍历。细节不在文档里，在 vendor/composer/autoload_psr4.php 生成后的实际内容中——有疑问，直接打开它看一眼映射是否符合预期。
