Linux服务器Class not found而本地能跑通，根本原因是文件系统大小写敏感性差异导致PSR-4自动加载路径不匹配：Linux严格区分User.php与user.php，而macOS/Windows默认不区分；需确保命名空间、目录路径（如app/Models/）、文件名（User.php）及composer.json中psr-4映射三者大小写完全一致。
Linux 服务器上 Class not found，但 macOS 或 Windows 本地能跑通——这基本就是大小写不一致导致的自动加载失败，不是代码逻辑问题，而是路径、命名空间、类名三者在文件系统层面没对齐。
为什么 Linux 上报错而本地不报？
根本原因是文件系统行为差异：Linux（ext4/xfs）和部分 macOS（APFS 大小写敏感卷）严格区分 User.php 和 user.php；而 macOS 默认 APFS 和 Windows NTFS 默认不区分，PHP 尝试加载 User 类时，即使磁盘上只有 user.php，系统也可能“帮忙匹配”成功。Composer 的 PSR-4 加载器不做模糊匹配，它只按字符串拼接路径，然后调用 file_exists() —— 这个函数在 Linux 下返回 false，就直接抛异常。
-
namespace AppModelsUser;声明要求目录必须是app/Models/（首字母大写），不能是app/models/ - 类名
User必须对应文件名User.php，不是user.php、USER.PHP或UserController.php -
composer.json中"App\": "app/"的映射路径，末尾斜杠和反斜杠转义必须正确，否则生成的autoload_psr4.php里路径就错了
怎么快速定位哪一环出问题？
别猜，直接查生成的映射和真实文件：
- 运行
composer dump-autoload -v，看终端输出是否扫描了你的目录（例如Scanning /path/to/project/app/Models for namespace AppModels） - 打开
vendor/composer/autoload_psr4.php，搜索你的命名空间前缀（如AppModels），确认生成的路径字符串和你ls -l app/Models/User.php看到的完全一致 - 检查类文件第一行
namespace声明：必须无空格、无 tab、结尾有分号，且与目录结构逐级对应（AppModelsUser→app/Models/User.php） - 用
find app/ -name "*User*" -o -name "*user*"查有没有大小写混用的残留文件
动态构造类名时最容易翻车
像 $class = "App\Lib\CRM\" . Str::studly($name); new $class 这种写法，在 Linux 上极脆弱——Str::studly("acme") 返回 "Acme"，但如果你的物理文件其实是 app/Lib/CRM/acme.php，那自动加载器永远找不到它。
- 不要依赖字符串转换隐式推导文件名，改用白名单映射：
$map = ['acme' => 'Acme', 'hubspot' => 'HubSpot'] - 在实例化前加运行时校验：
if (!class_exists($class)) { throw new RuntimeException("Class {$class} not found"); } - CI 流水线必须用 Linux 容器执行
composer install和基础类加载测试，Windows/macOS “能跑”不等于“正确”
Git 不报错，但文件名大小写变更已失效
这是协作中最隐蔽的坑：git status 在默认配置下不会显示 User.php → user.php 的变更，因为 core.ignorecase = true 是 Git 在 macOS/Windows 上的默认行为。协作者拉取后，那个文件可能直接消失或加载失败。
- 立即检查：
git config core.ignorecase，若输出true，说明当前仓库已关闭大小写敏感 - 临时修复：
git config core.ignorecase false && git rm --cached User.php && git add user.php - 长期方案：项目根目录加
.gitattributes文件，写入* text=auto eol=lf，并配合 pre-commit 脚本检查 PascalCase 命名
真正麻烦的从来不是改一个文件名，而是改完之后忘了重新运行 composer dump-autoload，或者团队成员仍在用旧镜像开发。跨平台兼容性不是靠“本地能跑”验证的，它必须由 CI 中的 Linux 环境来兜底。
