必须执行 composer dump-autoload 的场景仅限新增类、修改 autoload 配置或移动文件后未同步命名空间；class not found 多因配置错误或路径问题，而非未执行该命令。
不需要每次改代码都执行 composer dump-autoload，它只在自动加载映射“没更新”时才起作用——比如你新增了类、改了 composer.json 里的 autoload 配置，或移动了文件但命名空间没同步。多数报错（如 Class not found）不是命令没跑，而是配置写错、路径不对、或根本没触发重生成。
Class not found 但文件和命名空间都对，该不该跑 dump-autoload？
该，但得先确认是不是真属于需要手动刷新的场景：
- 新增了一个类文件（如
src/Services/PaymentService.php），且已声明namespace AppServices;，但new PaymentService()报错 → 必须跑 - 把类从
app/Models/User.php移到app/Domain/User.php，同时改了命名空间为AppDomain，但没在composer.json的autoload.psr-4里加"App\Domain\": "app/Domain/"→ 光跑命令没用，先补配置 - 只改了
PaymentService里某个方法的逻辑 → 完全不用跑 - 运行过
composer install或composer update→ 通常已自动完成，不必再手动 dump
用了 classmap 加载方式，为什么 dump-autoload 后类还是找不到？
classmap 不是“配完就生效”，它依赖扫描结果写入 vendor/composer/autoload_classmap.php，出错常因路径或内容不合规：
-
composer.json中classmap字段值必须是相对路径（如"lib/"），不能带./或绝对路径 - 目标目录下存在语法错误的
.php文件（哪怕只是少个分号），dump-autoload会静默跳过，不报错也不映射 - 目录里混入了
.php5、.inc等非默认扩展名文件，默认不扫描 - 执行命令时当前工作目录不是项目根目录 → 路径解析失败，映射为空
- 没加
-v参数，看不到扫描过程；加了才能确认是否扫到了目标目录、跳过了哪些文件
最直接验证方式：打开 vendor/composer/autoload_classmap.php，搜索你的类名。没出现，说明根本没被扫进去。
什么时候必须加 -o 参数？
composer dump-autoload -o 是生成 classmap 映射表，不是“优化一下而已”——它会扫描所有 PSR-4 目录和 files 列表，把每个类名硬编码进大数组，启动时跳过文件系统遍历。但它的生效前提是：
- 你确实需要性能提升（如 CLI 命令频繁启动、高并发 Web 请求）
- 项目结构稳定，不会频繁增删类文件（否则每次都要手动
dump-autoload -o） - 没混用运行时
require动态加载的类（-o模式下这些类无法被自动加载） - 生产环境打包或 CI 构建阶段使用，开发时通常不加
- 若还加了
--classmap-authoritative，Autoloader 将完全信任 classmap，不再 fallback 到 PSR-4 查找 —— 这步能省一次stat()系统调用，但也意味着漏映射=必报错
post-autoload-dump 钩子到底在什么时候执行？
它不是“安装后”或“更新后”，而是“自动加载文件真正写完那一刻”触发，时机非常确定：
- 执行
composer dump-autoload（无论是否带-o） - 执行
composer install且检测到 autoload 配置变更或首次生成vendor/autoload.php - 执行
composer update后需重写 autoload 映射文件 - 执行
composer require新包，且该包含 autoload 配置，触发自动 dump
典型用途是清理框架缓存（如 php artisan config:clear）、通知 IDE 重新索引、或生成额外的类映射缓存。注意：它不保证依赖已全部安装完毕（post-install-cmd 才是那个时机），只管 autoload 文件落盘。
最容易被忽略的一点：Composer 不监听文件系统变化，也不会自动感知你新建了一个 PHP 类。它只认映射表——而这张表只在 install、update 或显式 dump-autoload 时重写。别指望保存文件后它就“自动刷新”。
