addClassMap()适用于类路径与命名空间不匹配、无命名空间旧类、高频调用类及测试替换等场景；需用绝对路径、注意大小写和反斜杠，注册后仍需use声明，宜在app/common.php中批量初始化并校验文件存在。
类库映射不是“必须做”的步骤，但当你频繁加载固定几个非标准路径的类（比如 org\util\Array、自定义 SDK 类、历史遗留类），又不想改目录结构或迁移到 PSR-4 时，addClassMap() 是最直接、开销最低的解法。
什么时候该用 addClassMap() 而不是依赖自动加载？
自动加载（PSR-4）靠目录结构推导文件路径，一旦类文件不在命名空间对应位置，就会失败。而类库映射是“硬绑定”，绕过路径推导，适合以下场景：
- 类文件放在
extend/或vendor/外部目录，且命名空间与路径不一致 - 需要加载没有命名空间的旧类（如
class Array {}），但又想用use org\util\Array方式引用 - 高频调用的类（如日志、缓存工具），想省掉每次解析命名空间路径的开销
- 测试阶段临时替换某个类，不改源码只换映射路径
addClassMap() 的参数和路径写法要点
第一个参数是完整类名（含命名空间），第二个参数是**绝对物理路径**，必须以 .php 结尾，且不能漏掉 LIB_PATH、EXTEND_PATH 等常量——它们不是字符串字面量，而是框架预定义的路径常量。
- 正确：
Loader::addClassMap('think\Log', LIB_PATH . 'think\Log.php') - 错误：
Loader::addClassMap('think\Log', 'think/Log.php')（相对路径，找不到文件） - 错误：
Loader::addClassMap('org\util\Array', EXTEND_PATH . 'array.php')（类名大小写不匹配，Array≠array） - Windows 下注意反斜杠：
APP_PATH . 'index\vv\Test.php'，别混用/和\
映射后怎么用？别漏掉 use 和命名空间声明
映射只是告诉 Loader：“这个类名 → 对应这个文件”，但 PHP 解析器仍按常规规则检查命名空间。所以：
立即学习“PHP免费学习笔记（深入）”；
- 在使用类的文件顶部，必须写
use think\Log;或use org\util\Array; - 如果类本身没定义命名空间（即全局命名空间），映射名也得用全局形式：
Loader::addClassMap('Test', APP_PATH . 'test\Test.php')，然后用new \Test()（注意开头的反斜杠） - 映射不改变类内部逻辑，如果类里用了
namespace org\util;，那映射名就必须是org\util\Array，不能简写
批量映射和位置选择：别在控制器里调用
映射只需注册一次，重复调用无害但浪费。最佳实践是写在应用初始化阶段：
- 推荐位置：
app/common.php（全局生效）或app/provider.php（TP6+） - 批量写法：
$map = ['think\Log' => LIB_PATH . 'think\Log.php', 'org\util\Array' => EXTEND_PATH . 'org\util\Array.php']; Loader::addClassMap($map); - 别在控制器方法里调用
addClassMap()：每次请求都执行，既没必要，还可能因顺序问题导致类未加载就实例化 - 映射注册后，类文件不会立刻被 require，只有首次
new或static::调用时才触发加载
真正容易被忽略的是路径常量拼接后的实际结果是否真实存在——建议在注册后加一行 is_file($path) 检查，否则静默失败，调试时只能看到 “Class not found” 而不是具体哪个路径错了。
