Composer从不自动刷新autoload配置，vendor/autoload.php是静态生成的，必须手动执行composer dump-autoload才能更新映射；本地包需自身composer.json声明autoload且满足path仓库四条件，否则autoload不生效。
composer install/update 后不自动 reload autoload 配置
Composer 从不“自动刷新”自动加载配置——vendor/autoload.php 是静态生成的，内容来自 composer.json 中的 autoload 字段和当时执行 dump-autoload 的结果。哪怕你改了命名空间映射、加了新文件、甚至删了整个 src/ 目录，只要不重新运行命令，autoload.php 就不会变。
常见错误现象：Class not found 却确认类文件存在、命名空间也对，原因八成是漏了这步：
-
composer dump-autoload没执行（尤其在本地开发中手动增删类后） - CI 环境里只跑
composer install，没加--optimize-autoloader或没触发dump-autoload - 项目用了
path类型仓库，但本地包的composer.json里autoload写错路径或没加psr-4映射
Git commit hook 自动触发 dump-autoload
想在每次提交前检查并刷新 autoload，可以用 pre-commit 钩子。它不依赖 CI，适合本地开发快速验证结构变更是否可加载。
操作步骤（以 husky 或原生 .git/hooks/pre-commit 为例）：
- 确保项目根目录下
composer.json的autoload和autoload-dev配置正确 - 在钩子里执行：
composer dump-autoload --no-interaction - 加个简单校验：如果
vendor/autoload.php不存在或生成失败，中断提交（避免带坏配置推上去） - 注意：不要在钩子里加
--optimize-autoloader，它会生成 classmap，而 classmap 不会随文件增删自动更新，反而掩盖问题
GitHub Actions 中 autoload 同步失效的典型场景
CI 流水线里 composer install 成功，但测试报 Class not found，往往不是 autoload 配置错，而是环境没对齐：
- PHP 版本与
composer.json中"php": "^8.2"不匹配 →install直接跳过 autoload 生成 - 没显式启用
mbstring或xml扩展 → Composer 解析composer.json失败，静默跳过 autoload 步骤 - 缓存只用了
~/.composer/cache，没缓存vendor/→ 每次都重装，但dump-autoload只在install时隐式触发一次；若中间有脚本修改了src/，后续步骤无法感知 - 使用了
path仓库，但 CI 工作目录里没有packages/my-utils/.git→ Composer 认为该 path 无效，不软链也不加载其 autoload
require 本地包后 autoload 不生效的硬性条件
用 path 仓库引入本地包，autoload 要生效，必须同时满足以下四点，缺一不可：
-
repositories块写在项目根composer.json顶层，且url是相对路径（如"./packages/utils"），不能含file://或绝对路径 - 本地包目录下有合法
composer.json，含"name"（如"myorg/utils"）和"version": "dev-main" - 项目根
composer.json中require必须写"myorg/utils": "dev-main"，不能是*或^1.0 - 本地包自己的
composer.json里写了正确的autoload，比如："psr-4": { "MyOrg\Utils\": "src/" }，末尾反斜杠和路径斜杠都不能少
最易被忽略的是第四点：很多人以为只要主项目配置了 autoload 就能覆盖子包，其实每个包的 autoload 是独立注册的，子包的 autoload 必须自己声明、自己生效。
