classmap 是 Composer 加载非标准目录类的最直接方案，通过在 composer.json 的 autoload.classmap 中配置相对路径（支持文件或目录），运行 composer dump-autoload 后生成映射并生效；它不依赖命名空间或文件名，但需避免与 PSR-4 路径重叠以防重复定义错误。
classmap 怎么让 Composer 加载非标准目录的类
Composer 默认只 autoload src/ 或 lib/ 下符合 PSR-4/PSR-0 的类。如果项目里混着一堆散装 PHP 文件（比如旧系统迁移来的 utils.php、helpers/ 目录），又不想改文件结构或加命名空间，classmap 是最直接的解法。
它不依赖文件名或命名空间，只认 require 时能定位到的路径——只要文件里定义了类（哪怕只有一个 class Foo），就能被扫进去。
- 在
composer.json的"autoload"下加"classmap"数组，填相对路径（支持文件或目录） - 路径是相对于
composer.json所在位置的，不是相对于vendor/ - 运行
composer dump-autoload后才会生效，别忘了这步 - 目录会递归扫描，但不会跳过子目录里的
.git或vendor/，所以别把整个vendor/往里塞
"autoload": {
"classmap": [
"legacy/classes/",
"helpers/functions.php",
"old_app/model.php"
]
}
classmap 和 psr-4 混用时谁先加载
加载顺序取决于你在 composer.json 里写的顺序：classmap 在前就先查 classmap，匹配到了就不再往后找；反之亦然。但实际中，这个顺序几乎不影响结果——因为 PSR-4 要求类名和路径严格对应，而 classmap 是“有类就加载”，两者覆盖范围通常不重叠。
- 如果你把
src/同时写进psr-4和classmap，classmap 会把所有 PHP 文件无差别加载，可能触发重复定义错误（Fatal error: Cannot declare class X） - classmap 不做命名空间校验，哪怕
Foo.php里写了namespace Bar;，它也照单全收——但运行时如果 PSR-4 已经加载过同名类，就会报错 - 想安全混用，确保 classmap 只指向那些没被 PSR-4 / PSR-0 覆盖的路径，比如
legacy/、thirdparty/
classmap 导致 autoload 失败的常见错误
最典型的不是语法错，而是路径错或缓存没更新。Composer 不会在每次 require 时重新扫描 classmap，它把映射关系固化在 vendor/composer/autoload_classmap.php 里。
- 改了
composer.json的classmap但没跑composer dump-autoload→ 新路径根本不会进 classmap 文件 - 路径写成绝对路径（如
/var/www/project/old/）→ Composer 生成的 classmap 是硬编码路径，换环境就失效 - 文件里只有函数、没有
class或interface→ classmap 会忽略它，得用filesautoload 类型 - 文件编码是 GBK 或含 BOM → Composer 解析失败，classmap 条目消失，且不报错，只能手动检查
autoload_classmap.php
比 classmap 更轻量的替代方案：files
如果只是要加载几个全局函数（比如 str_slug()、array_flatten()），别用 classmap。它专为类设计，对纯函数文件无效。
- 改用
"files"字段，同样写在"autoload"下，路径规则和 classmap 一致 -
files会在 Composer autoloader 初始化时require_once这些文件，一次加载，全程可用 - 注意：它不支持目录，只能列具体文件；也不能用通配符；多个文件按数组顺序加载，有依赖关系时得排好序
"autoload": {
"files": [
"helpers/functions.php",
"config/constants.php"
]
}
classmap 的本质是“懒加载类”，files 是“启动即加载脚本”。选哪个，看你要的是类还是函数，以及是否愿意承担额外的 require 开销。
