必须加 -o 参数才能加载新类：composer dump-autoload -o 会全量扫描并重建 classmap，否则仅更新 PSR-4 映射，不扫描磁盘文件，新增的 AppServicesPaymentService 将无法被找到。
composer dump-autoload 不加 -o 就等于没重载
你新增了 AppServicesPaymentService，运行时却报 Class "AppServicesPaymentService" not found？不是命名空间写错了，也不是文件放错目录了——大概率是只执行了 composer dump-autoload，没加 -o。
不加参数时，Composer 只更新 vendor/composer/autoload_psr4.php 这类配置映射，**完全不扫描磁盘上的 PHP 文件**。也就是说，它根本不知道你新写了类、改了路径、删了旧文件。classmap（类名 → 文件路径的静态表）压根没重建，旧的 autoload 文件还在用过期的“地图”。
-
composer dump-autoload：仅刷新 PSR 映射路径，适合只改了"psr-4"配置但没动类文件本身 -
composer dump-autoload -o：清空旧autoload_classmap.php，全量扫描所有 autoload 配置目录（如src/、lib/），生成全新 classmap -
composer dump-autoload --no-dev -o：生产部署必备，跳过tests/等 dev 目录，classmap 更小、加载更快
什么时候必须手动运行 dump-autoload？
别等 composer install 或 update 顺带帮你做——它们不一定触发完整 autoload 刷新，尤其在 CI/CD 或容器构建中容易漏掉。
以下情况不手动跑一次 composer dump-autoload -o，类就永远加载不到：
- 你把
src/Models/User.php移到了src/Domain/User.php，且已更新composer.json中的 PSR-4 映射 - 新增了
"classmap": ["legacy/"]配置，但 legacy 目录下已有十几个老类文件 - CI 流水线先跑了
composer install --no-dev，之后又合入了仅用于本地开发的 CLI 工具类（在bin/下），需要补扫 - IDE 提示类存在，但 PHP 运行时报错——很可能是 autoload 文件缓存了旧状态，而 IDE 索引是实时的
files 和 classmap 配置改了，光 dump 不够，还得注意位置
"files" 必须放在 composer.json 的 autoload 顶层，**不能塞进 autoload-dev**。否则即使你本地 composer dump-autoload 成功，一上生产环境（--no-dev）这些函数文件就彻底消失，Call to undefined function 直接报给你看。
同理，"classmap" 是靠扫描生成的，不是声明即生效。比如你加了：
"autoload": {
"classmap": ["utils/"]
}那必须紧接着跑
composer dump-autoload -o，否则 utils/Helper.php 里的 Helper 类照样找不到。
-
"files"路径是相对composer.json的，不是 vendor 或入口文件 -
"files"数组顺序 = 加载顺序，有依赖关系时得自己排好 -
"classmap"扫描是递归的，但不会自动包含子目录里新创建的文件——新增就得再 dump 一次
验证是否真生效，别只信 IDE 或缓存
最直接的验证方式，一行命令搞定：
composer dump-autoload -o && php -r "require 'vendor/autoload.php'; var_dump(class_exists('App\Services\PaymentService'));"
输出 bool(true) 才算真正成功。如果还是 false，说明要么类文件没被扫到（检查路径、命名空间、文件后缀），要么 autoload 配置根本没写对（比如 "App": "src/" 少了个反斜杠，变成 "App"）。
还可以直接打开生成的映射文件看：
— vendor/composer/autoload_classmap.php：搜你的类名，确认路径对不对
— vendor/composer/autoload_psr4.php：核对命名空间前缀和目录是否匹配
classmap 生成逻辑依赖文件系统实时状态，而 Composer 缓存或 IDE 索引滞后常让人误判问题出在配置上——其实只是 autoload 文件根本没包含那个类。
