Composer dump-autoload命令在什么情况下必须手动执行？

必须执行 composer dump-autoload 更新自动加载映射，开发中改 autoload 配置或新增类后需运行该命令；生产环境应加 -o 参数生成 classmap 提升性能，CI/CD 构建时需显式添加 –optimize-autoloader 或 dump-autoload -o。

新增类文件后类找不到（Class not found）

你手动加了一个新类，比如 app/Services/PaymentService.php，命名空间是 AppServices，也已在 composer.json 的 autoload.psr-4 里配好了：

"autoload": {
  "psr-4": {
    "App\": "app/"
  }
}

但一运行就报 Class 'AppServicesPaymentService' not found——这不是路径或命名空间写错了，而是 Composer 还不知道这个文件存在。

• 根本原因：Composer 的自动加载映射（如 vendor/composer/autoload_psr4.php）是静态生成的，不会监听文件系统变化
• 必须执行：composer dump-autoload，它会重新扫描 app/ 目录，把新类注册进映射表
• 开发中改完 composer.json 的 autoload 配置后，同样要跑这一句，否则配置不生效

部署到生产环境前必须加 -o 参数优化

线上环境不能靠 PSR-4 运行时遍历目录找类，太慢。要用 classmap 提前固化类名与路径的对应关系，避免 I/O 开销。

• 错误做法：composer dump-autoload（无参数）→ 仍保留动态查找逻辑
• 正确做法：composer dump-autoload -o 或 composer dump-autoload --optimize
• 效果：生成紧凑的 autoload_classmap.php，所有类直接查表，启动快、内存少
• 注意：-o 会扫描整个 autoload 范围（含 vendor 中标记为可 autoload 的包），耗时略长，别在热更新时频繁执行

用了 classmap 或 files 类型自动加载时，改完就得重 dump

比如你在 composer.json 里写了：

"autoload": {
  "classmap": ["database/seeds/", "app/Exceptions/Handler.php"],
  "files": ["app/Helpers/functions.php"]
}

之后又往 database/seeds/ 加了个 UserTableSeeder.php，或者改了 functions.php 的函数签名——这些变更不会被自动感知。

• classmap 是一次性快照，新增文件必须重扫；files 是硬加载列表，增删都要同步更新映射
• 必须执行：composer dump-autoload（哪怕只改了一个文件）
• 调试时可加 -vvv 看它到底扫了哪些路径：composer dump-autoload -vvv

最容易被忽略的是：CI/CD 构建阶段只跑 composer install，却没加 --optimize-autoloader 或后续 dump-autoload -o，结果上线后性能掉一截；还有人以为 composer update 会自动覆盖 autoload，其实它只在依赖变动时触发 post-autoload-dump，本地改了类却不提交 composer.lock，那这一步就压根没跑。