需手动执行 composer dump-autoload 生效，且仅读取根目录 composer.json；PSR-4 命名空间末尾须带反斜杠，classmap 路径须真实存在；混用时避免空命名空间 PSR-4；动态加载可用 $loader->addPsr4()；autoload-dev 不参与生产环境加载。
composer.json 里 autoload 字段怎么配才生效
改了 autoload 却发现 composer dump-autoload 后类还是找不到，大概率是路径没对上或未触发重生成。Composer 不会自动监听 composer.json 变更，必须手动执行命令；而且它只读取根目录下的 composer.json，子包里的 autoload 配置不会被主项目自动合并。
实操建议：
- 确保修改的是项目根目录的
composer.json，不是 vendor 里某个包的 - 用
composer dump-autoload -o（优化模式）生成静态映射，开发阶段可先省略-o加快调试 - 检查
psr-4的命名空间末尾是否带反斜杠（"App\": "src/"✅，"App": "src/"❌） - 如果用了
classmap，路径必须指向实际存在的目录或文件，不支持通配符
PSR-4 和 classmap 混用时要注意什么
PSR-4 适合常规命名空间映射，classmap 更适合遗留代码或动态生成的类——但二者混用容易引发优先级冲突和加载顺序问题。Composer 默认按配置顺序处理 autoload 类型，但 PSR-4 匹配失败后不会 fallback 到 classmap，而是直接抛出 Class not found。
常见错误现象：类文件明明在 classmap 扫描路径里，却报错找不到。
原因通常是 PSR-4 规则“拦住了”匹配——比如你写了 "": "legacy/" 这种空命名空间 PSR-4 映射，它会尝试把所有类名都按文件路径拼接去查，反而绕过了 classmap。
实操建议：
- 避免空命名空间 PSR-4 映射（
"": "xxx"），改用classmap或明确的前缀 - classmap 路径尽量具体，比如
"classmap": ["lib/Helper.php", "legacy/"]，别写成"./" - 运行
composer show -s查看当前生效的 autoload 规则，确认顺序和内容
开发中动态加路径，不改 composer.json 怎么办
单元测试、插件热加载、CLI 工具临时扩展等场景，需要在运行时注入额外的自动加载逻辑，不能每次改配置都跑一遍 dump-autoload。
Composer 生成的 autoloader 是一个标准 PSR-0/4 兼容对象，可通过 ClassLoader 实例操作：
$loader = require __DIR__ . '/vendor/autoload.php';
$loader->addPsr4('Test\', __DIR__ . '/tests/stubs/');
$loader->addClassMap(['MyLegacyClass' => __DIR__ . '/lib/old.php']);
注意点：
-
addPsr4()第二个参数必须是绝对路径，相对路径不会自动解析 -
addClassMap()不会扫描文件，只注册已知类名到文件的映射，适合少量确定存在的类 - 这种动态注册只对当前请求有效，不影响
vendor/autoload.php的静态行为
autoload-dev 为什么不能用在生产环境
autoload-dev 里的规则（如 psr-4 或 classmap）默认不会被 composer install --no-dev 加载，且生成的 autoloader 文件里根本不会包含它们。这不是“性能开关”，而是构建隔离机制。
典型误用：把测试工具类或 Mock 类放在 autoload-dev，然后在生产代码里 new TestHelper() —— 本地能跑，上线就 Class not found。
实操建议：
-
autoload-dev只放真正只用于开发/测试的类，比如 PHPUnit 扩展、Faker 提供器、自定义 assertion 类 - 想让某部分代码“可选加载”，应该用条件 require 或服务容器绑定，而不是依赖 autoload-dev
- CI 环境务必用
--no-dev验证，避免漏掉隐式依赖
autoload 的灵活性背后是路径解析和命名空间匹配两层逻辑，多数问题出在“以为路径对了”和“以为规则生效了”之间——多看 vendor/composer/autoload_psr4.php 生成的内容，比反复猜更可靠。
