Composer dump-autoload 不生效是因为新增类未被 autoload 配置覆盖：PSR-4 要求路径与命名空间严格匹配；非标准路径需显式声明；-o 仅优化 classmap，对 PSR-4 新类无效；-a 将 PSR-4 转为静态映射，开发中慎用；autoload-dev 类需 --dev 才生效；autoload.files 文件必须含可执行代码。
为什么 composer dump-autoload 有时不生效？
因为 Composer 默认只扫描 autoload 配置里声明的目录和命名空间，新增类文件没被收录，class_exists() 或 new 实例化时就会报 Class not found。不是 autoload 坏了，是它根本不知道有这个类。
常见错误现象：composer install 后新加了一个 App/Service/Helper.php，但运行时报错 Class 'AppServiceHelper' not found，而 composer dump-autoload 执行完也没用。
- 确认
composer.json的autoload段是否覆盖该路径（比如用了"psr-4": {"App\": "app/"}，那文件必须在app/Service/Helper.php，且命名空间为AppService） - 如果类在非标准路径（如
scripts/或tests/），要显式加到autoload.files或autoload.psr-4里 - 执行
composer dump-autoload -o（优化模式）会生成vendor/composer/autoload_classmap.php，但仅对classmap类型有效；PSR-4 不依赖 classmap，所以加-o对 PSR-4 新类无帮助
什么时候该用 dump-autoload -a？
-a（即 --optimize-autoloader）不是“让自动加载更快”，而是把所有 PSR-4/PSR-0 映射转成静态 classmap——适合部署环境，但开发中反而容易掩盖路径配置问题。
使用场景：上线前构建镜像、CI 流水线打包、或你确定所有类都已稳定且不会频繁增删。
- 启用后，Composer 不再动态解析 PSR-4 路径，而是查生成好的 classmap 数组，所以新增类必须重新
dump-autoload -a才能被识别 - 本地开发慎用
-a：改一个文件就得重跑命令，否则Class not found会反复出现 -
dump-autoload -a会忽略autoload-dev中的配置，除非加--dev
autoload-dev 里的类为啥总报错？
因为 autoload-dev 只在 composer install --dev（默认行为）或 composer dump-autoload 时生效；但如果你用 composer install --no-dev 上线，这些类路径根本不会写入 autoload 文件，自然 Class not found。
典型例子：测试工具类 Tests/Support/FakeUser.php 在 autoload-dev.psr-4 里声明了，但生产环境运行时报错。
- 检查当前环境是否安装了 dev 依赖：
composer show | grep phpunit，如果没输出，说明--no-dev被用了 - 确保
dump-autoload时带上--dev（尤其 CI 中显式调用时） - 不要把运行时必需的类（比如封装的异常类、基础 Trait）放在
autoload-dev里——它们不是“开发专用”
手动 require 文件后仍 Class not found 怎么办？
Composer 支持 autoload.files 直接载入 PHP 文件，但有个硬性限制：文件里不能只定义类，还必须有可执行代码（哪怕只是 defined('APP_START') || die();），否则 Composer 会跳过它。
错误写法：helpers.php 里只有 class Helper { }，结果 dump-autoload 后依然找不到。
- 在
helpers.php开头加一行<?php // helper bootstrap或if (false) {}即可满足“有可执行内容”条件 -
autoload.files是绝对路径解析，推荐用__DIR__ . '/helpers.php'这种写法，避免相对路径失效 - 修改
autoload.files后必须composer dump-autoload，它不会自动监听文件变化
最常被忽略的是命名空间与物理路径的严格对应关系——Composer 不猜，只匹配。少一个反斜杠、多一个空格、大小写不一致（尤其在 Linux 环境下），都会导致 Class not found，而且错误信息从不提示哪里错了。
