Composer使用排错：处理因文件系统大小写敏感导致的加载失败

Composer autoload 找不到类但文件存在，主因是大小写不匹配：PSR-4 要求命名空间、目录路径、文件名三者严格大小写一致，Linux 等系统区分大小写，而 macOS/Windows 默认不区分，导致开发与部署环境行为不一致；需检查 composer.json 的 psr-4 映射、真实文件名拼写、autoload_psr4.php 生成路径，并统一使用 PascalCase 命名规范。

Composer autoload 为什么找不到类，但文件明明存在？

这大概率是大小写不匹配——代码里写着 use AppModelsUser，实际文件名却是 User.php 或 user.php。文件系统（比如 macOS 默认的 APFS 大小写不敏感，Linux ext4 大小写敏感）和 Composer 的 PSR-4 自动加载规则一错位，就砸了。

PSR-4 的规则很死板：命名空间与目录结构必须严格大小写一致。Composer 不会自作聪明去猜你是不是想用 user.php 加载 User 类，它只按路径字符串精确匹配。

• 检查 composer.json 中 "autoload" 下的 "psr-4" 映射，确认前缀（如 "App"）对应的真实路径是否拼写一致
• 进入项目根目录，执行 find app/ -name "*.php" | grep -i user，看看真实文件名的大小写
• 运行 composer dump-autoload -o 后，打开 vendor/composer/autoload_psr4.php，搜索你的命名空间前缀，确认生成的路径字符串里有没有大写错误

Mac 上开发、Linux 上部署时突然报 Class not found

Mac 默认文件系统对大小写不敏感，User.php 和 user.php 在 Finder 或终端里看着一样，但 Composer 生成的 autoloader 会记住你创建时用的大小写。一旦部署到 Linux，文件系统直接拒绝匹配，瞬间崩掉。

• 别依赖 Mac 的“宽容”。从第一天起就用 PascalCase 统一命名：类名 User → 文件名 User.php，命名空间 AppModels → 目录必须是 app/Models/（不是 app/models/）
• CI 流程中加入检查：用 composer validate --strict 加上自定义脚本，比对 src/ 下所有 *.php 文件名与其中 class 声明是否首字母大写且驼峰一致
• 本地开发可以临时启用 Mac 的大小写敏感卷（需要重装系统或新建磁盘分区），但更现实的做法是用 Docker 跑一个 Alpine 或 Ubuntu 容器做日常开发，提前暴露路径大小写问题

vendor/composer/autoload_classmap.php 里路径全是小写，但类名是大写的

这是 classmap 模式的行为特征：它扫描文件后，把文件路径作为键、完整类名作为值存进数组，但路径本身是操作系统返回的原始字符串。如果扫描时目录名是 models，那即使类名叫 AppModelsUser，路径也记成 app/models/User.php——加载时 Composer 会尝试读这个路径，Linux 下直接 404。

• classmap 不校验命名空间与路径的关系，只认物理路径，所以它比 PSR-4 更容易因大小写翻车
• 避免混用：要么全用 PSR-4（推荐），要么确保 classmap 扫描前所有目录名已经符合命名空间的大小写（例如先 git mv app/models app/Models）
• 检查 classmap 来源：在 composer.json 中搜索 "classmap"，确认有没有意外包含了 app/models 这类小写路径

怎么快速定位是哪个文件/路径导致 autoload 失败？

别靠猜。Composer 提供了调试入口，关键是让错误信息暴露真实路径请求。

• 临时修改 vendor/composer/AutoloadClassLoader.php，在 findFile() 方法开头加一行：echo "Looking for: $class";，再触发一次 autoload，就能看到它究竟在找什么完整类名
• 用 composer show --path 查每个包的实际安装路径，确认没有意外的符号链接或大小写混杂的挂载点
• 运行 php -d display_errors=1 -r "var_dump(composerAutoloadClassLoader::getRegisteredLoaders());" 看当前注册的 loader 实例及其映射，注意路径字符串里的大小写

大小写问题不会报“大小写错误”，只会静默失败或抛出 Class not found。最麻烦的是它在某些环境能跑，在另一些环境崩，所以验证不能只靠本地。每次改完命名空间或移动文件，立刻在目标部署环境的最小容器里跑一遍 php -r "require 'vendor/autoload.php'; new AppModelsUser();"。