Composer的classmap配置：一份被低估的“静态地图”

classmap配置必须执行composer dump-autoload才生效

这里有个关键点，很多开发者都会踩坑：classmap本质上是一份“静态地图”，它不是实时扫描目录的机制。这意味着，无论你是在composer.json里修改了"classmap"字段，还是新增、删除了类文件，都不会立刻影响那份已经生成的autoload_classmap.php文件。除非，你手动触发重建。

典型的错误场景就是：控制台抛出Class 'ClassA' not found，但你明明看到libs/ClassA.php文件就在那里，而且composer.json里也早就把"libs/"加进了classmap数组。问题出在哪？就差最后一步——重建映射。

• 开发阶段，记得运行composer dump-autoload；生产部署，则建议用composer dump-autoload --optimize。
• 有个细节：如果只是改了类文件的内容，没动文件名或路径，那确实不需要重跑。但只要涉及文件的增、删、移动，这个命令就必须执行。
• 另外，composer install或update默认并不会帮你重建classmap，除非你加上--optimize-autoloader这个标志。

classmap支持无命名空间和带命名空间的类混用

classmap有个很大的优点：它不解析命名空间，只管建立“类名”到“文件路径”的硬映射。所以，无论是老掉牙的ClassA，还是遵循PSR的App\Utils\Helper，甚至是第三方遗留的Vendor\Legacy\OldClass，都可以被塞进同一个classmap目录下，Composer照单全收。

这个特性在迁移老项目时尤其好用。面对大量没有命名空间的类，或者那些不遵循PSR标准的第三方SDK（比如直接定义class WeChatAPI），与其大动干戈去改命名空间和目录结构，不如直接用classmap来得省事。

• 目录支持嵌套，classmap值填目录路径就行，Composer会自动递归扫描所有.php文件。
• 注意，同一个类名不能出现在多个路径下，否则在autoload_classmap.php里，后扫描到的会覆盖前面的——毕竟PHP数组的键是唯一的。
• 但如果两个不同命名空间下存在同名类（比如MyApp\User和Legacy\User），classmap依然能区分开，因为映射表的键是包含反斜杠的完整类名。

classmap性能优于PSR-4，但灵活性差

为什么说classmap加载快？看看autoload_classmap.php的内容就明白了，它本质上就是一个大数组：['ClassName' => '/abs/path/to/file.php']。查找类就是一次O(1)的哈希操作。相比之下，PSR-4需要根据命名空间拼接路径，再去检查文件是否存在，涉及多次I/O，自然慢一些。

但是，天下没有免费的午餐。性能提升的代价是灵活性下降：每次增删类文件，都必须重新生成映射表，这对于开发阶段频繁热更新的场景就不太友好。而且，它也不能像PSR-4那样，仅凭命名空间前缀就自动适配新增加的类。

• 对于生产环境，强烈建议在composer.json的根级配置中启用"optimize-autoloader": true。这样，当你运行composer install --no-dev时，就会自动触发--optimize操作。
• 千万别把整个vendor/目录塞进classmap——Composer自己管理的包已经优化过了，重复加入只会拖慢dump速度。
• 如果你的类文件数量极少，有时候用“files”方式直接require单个文件，可能比配置classmap更轻量。

classmap路径必须是相对项目根目录的路径

配置classmap时，路径怎么写也是个容易出错的地方。composer.json中classmap数组里的路径，必须是相对于该文件所在目录（也就是项目根目录）的相对路径。既不是相对于vendor/autoload.php，更不能用绝对路径。

典型的错误写法有两种：一种是"./src/libs/"，这个./纯属多余；另一种是"/var/www/myapp/src/libs/"，使用绝对路径会导致dump-autoload失败，并报错Invalid classmap path。

• 正确的写法是："classmap": ["src/libs/", "legacy/"]。
• 路径末尾的斜杠加不加都行，但建议统一加上，这样可以明确表示这是一个目录，避免被误判为文件。
• 路径不能以../开头，也就是说，不能跨出项目根目录，Composer会直接拒绝这种操作。

最后，分享一个classmap最容易被忽略，也最让人头疼的特性：它不校验类名是否与文件内容匹配。哪怕Foo.php文件里定义的是class Bar，只要这个文件被扫描进去了，映射关系就会建立在'Bar'这个键上。问题在于，这个错误在加载阶段不会被发现，直到运行时才会报错，调试的时候很容易让人绕弯路。这一点，务必心里有数。