运行composer dump-autoload -o强制刷新并生成autoload_classmap.php，再检查vendor/composer/autoload_static.php是否包含对应命名空间与路径映射。
如何快速确认 composer.json 中的 autoload 配置是否生效
Composer 的自动加载不是写完就立刻可用的，必须执行 dump-autoload 或安装/更新依赖后生成映射文件。常见现象是类明明按 PSR-4 规则放好了，却报 Class not found —— 很可能只是没刷新自动加载缓存。
实操建议：
- 运行
composer dump-autoload -o（加-o强制优化，生成vendor/composer/autoload_classmap.php） - 检查
vendor/composer/autoload_static.php是否包含你声明的命名空间前缀和路径映射 - 用
composer show --platform确认当前 PHP 版本是否满足composer.json中config.platform.php的约束（版本不匹配会导致 autoload 生成逻辑降级）
PSR-4 和 classmap 混用时为什么某些类始终不被加载
PSR-4 是按命名空间前缀+目录映射的动态查找机制，classmap 是静态路径列表。两者共存时，Composer 会优先走 PSR-4 匹配；但如果命名空间前缀配置错误（比如多写了反斜杠、路径未以 / 结尾），PSR-4 查找失败，也不会 fallback 到 classmap —— classmap 只加载显式列出的文件。
实操建议：
- PSR-4 的 value 必须是**绝对路径或相对于
composer.json的相对路径**，且结尾带/（如"App\": "src/App/"） - classmap 条目应指向具体文件（
"src/Helpers/Str.php"）或含.php文件的目录（"src/Utils"），但不要混用src/Utils/和src/Utils - 运行
composer dump-autoload -d（debug 模式）可输出每条 autoload 规则实际扫描的路径，方便定位遗漏
composer install 和 composer update 对 autoload 的影响差异
二者都会触发 autoload 重建，但关键区别在于：前者只读取 composer.lock，保证环境一致性；后者会重新解析 composer.json 并更新 lock 文件 —— 如果你改了 autoload 配置但只跑 install，新规则不会生效。
实操建议：
- 修改
autoload或autoload-dev后，必须执行composer dump-autoload或composer update --lock（跳过包更新，只重写 lock 中 autoload 元数据） - CI 环境中若使用
--no-scripts，会跳过 autoload 生成，需手动补上composer dump-autoload -o - 注意
vendor/autoload.php是入口文件，它本身不包含映射逻辑，而是加载vendor/composer/autoload_real.php，后者才决定用哪种 loader（psr4 / classmap / files）
为什么在 CLI 和 Web 环境下 autoload 行为不一致
根本原因通常是工作目录（getcwd()）不同，导致相对路径解析结果不同。例如 "App\": "src/App/" 在 CLI 下从项目根执行没问题，但在 Web 服务器中（如 Apache DocumentRoot 设为 public/）就会让 Composer 尝试在 public/src/App/ 下找类。
实操建议：
- 所有 autoload 路径统一用
__DIR__ . '/src/App/'这类绝对路径写法（仅限autoload.files场景）；PSR-4/classmap 不支持动态路径，只能靠规范项目结构 - Web 环境下确保入口脚本（如
public/index.php）先chdir(__DIR__.'/..')回到项目根，再 requirevendor/autoload.php - 用
debug_print_backtrace()+echo getcwd()快速验证当前上下文路径
自动加载机制本身不复杂，但它的“隐式生效”特性容易掩盖路径、作用域、执行时机三者的耦合问题。最常被忽略的是：autoload 配置变更后，既没清缓存，也没验证生成的 autoload_static.php 内容是否真实包含你的映射。
