autoload-dev 需在 composer.json 顶层独立配置，仅用于开发测试类自动加载，必须显式执行 composer dump-autoload --dev 才生效，且不与 autoload 互通；常见错误包括键名拼写错误、嵌套位置错误、混用 psr-4 与 classmap、CI 中漏启用 dev 模式等。
autoload-dev 只在你明确需要为测试、调试或开发工具类提供独立自动加载时才配置，不是每个项目都必须写；它和 autoload 完全隔离，配了不生效、配错位置、漏执行命令，测试类就永远找不到。
autoload-dev 必须写在 composer.json 顶层，且键名不能拼错
它必须是 composer.json 根对象下的一个字段，和 autoload 并列，不能嵌套进 require-dev 或其他任意字段里。Composer 只认 autoload-dev 这个精确键名——大小写错（比如 autoloadDev）、缩进多了一格、或者被包进别的 object 里，整个配置都会被静默忽略。
- 常见错误现象：
phpunit报Class not found，但composer dump-autoload --dev不报错，vendor/autoload.php里也搜不到你的命名空间 - 验证方法：打开
vendor/composer/autoload_dev.php，看末尾数组里有没有你写的映射 - CI/CD 中失败但本地正常？很可能是 CI 脚本用了
composer install --no-dev，而你误把测试路径配进了autoload
psr-4 和 classmap 在 autoload-dev 里不能混用
Composer 加载器对 autoload-dev 内部的规则不做 fallback：如果同时声明了 psr-4 和 classmap，且某个类文件命名空间与目录结构不严格匹配（比如 tests/Helper.php 里写了 namespace AppTools;），psr-4 匹配失败后，不会退到 classmap 去扫描——直接抛出 Class not found。
- 新项目统一用
psr-4："Tests\": "tests/"，要求tests/Unit/ExampleTest.php里必须有namespace Tests\Unit; - 老项目或散装脚本（如
tests/bootstrap.php）用classmap："classmap": ["tests/bootstrap.php", "tests/helpers/"]，但每次增删文件后必须手动运行composer dump-autoload --dev - 绝对不要在一个
autoload-dev块里同时写两者
改完 composer.json 后必须显式运行 composer dump-autoload --dev
composer install 或 composer update 默认不会重新生成 autoload-dev 的映射逻辑，哪怕你加了 --dev。只有 composer dump-autoload --dev 才会更新 vendor/composer/autoload_dev.php，并让 vendor/autoload.php 在下次加载时包含它。
- 日常开发推荐：
composer dump-autoload --dev - CI 环境或怀疑 autoloader 污染时：
composer install --no-autoloader && composer dump-autoload --dev - 验证是否生效：
php -r "var_dump(class_exists('Tests\Unit\ExampleTest'));"，结果为true才算成功 - 别依赖“跑一次 phpunit 就好了”——它不触发 autoload 重建
最容易被忽略的是：autoload-dev 生效的前提，是 vendor/autoload.php 被正确引入，且这个文件本身必须是在启用了 dev 模式的情况下生成的。一旦你在生产部署后本地改了配置却没重跑 dump-autoload --dev，那 vendor/autoload.php 里就压根没有你的测试映射，所有后续排查都是在绕路。
