必须执行composer dump-autoload的情况包括：修改autoload配置（如新增目录、调整PSR-4映射）或新增类文件未被自动加载识别；常见错误是Class not found但文件存在且命名空间正确；仅改类内部逻辑则无需执行。
composer dump-autoload 什么时候必须执行
改了 autoload 配置（比如加了新目录、改了 psr-4 映射）或新增了类文件但没被自动加载识别到，就得手动刷新自动加载映射。Composer 不会实时监听文件变化，dump-autoload 就是告诉它“重新扫描并生成 vendor/autoload.php 里用的映射表”。
常见错误现象：Class not found 报错，但文件明明存在、命名空间也对——大概率是映射没更新。
- 新增一个
src/Helper/StringUtils.php，且composer.json里已配"psr-4": {"App\": "src/"}→ 必须运行composer dump-autoload - 把
src/改成app/并同步改了composer.json中的路径 → 不执行就加载不到任何新路径下的类 - 只改了类内部逻辑，没动文件位置或命名空间 → 完全不需要执行
dev 与 production 模式下 dump-autoload 行为差异
composer dump-autoload 默认按当前环境生成映射，但关键区别在优化级别：开发模式（dev）生成带完整路径和调试信息的映射；生产模式（prod）会跳过某些检查，并启用类映射优化（--optimize 效果类似）。
使用场景：CI/CD 构建时通常加 --no-dev --optimize，减少自动加载开销；本地开发调试则用默认命令更利于定位问题。
-
composer dump-autoload：生成完整映射，支持classmap+psr-4混合，可调试 -
composer dump-autoload --optimize：合并所有类到vendor/composer/autoload_classmap.php，启动更快，但新增类后必须重跑 -
composer dump-autoload --no-dev：忽略require-dev中的 autoload 配置，适合部署
autoload 自动触发失败的三个典型坑
不是所有修改都会让 dump-autoload 生效，下面这些情况容易白忙活：
-
composer.json格式错误（比如多了一个逗号），dump-autoload会静默失败，检查返回值或加-v参数看详细输出 - 用了
classmap但路径写成相对vendor/而非项目根目录，例如"classmap": ["vendor/mylib/src"]→ 应该是"classmap": ["mylib/src"]（假设mylib是 require 进来的包） - Windows 下路径分隔符混用（
和/），尤其在files数组中引入全局函数时，推荐统一用正斜杠
验证是否生效：查 vendor/composer/autoload_static.php 或 autoload_classmap.php 里有没有你新加的类名或路径。
不碰 composer.json 也能让新类被加载的方法
临时调试时不想改配置、又想快速加载某个类？有更轻量的方式，但仅限特定场景：
- 用
composer dump-autoload --classmap-authoritative强制只走 classmap（需先确保 classmap 已覆盖目标类），适合锁定依赖行为 - 直接在代码里
require_once特定文件（绕过 autoload），仅用于脚本调试，上线前务必删掉 - 如果只是单个工具类，加进
files数组比配 psr-4 更简单："autoload": { "files": ["src/helpers.php"] }然后记得再跑一次composer dump-autoload
真正复杂的 autoload 问题往往出在嵌套 vendor 包的 autoload 配置冲突，或者多个 composer.json（如 monorepo 场景）没统一管理 —— 这时候光 dump 没用，得先理清加载优先级。
