Git文件大小写引起的错误Bug 处理记录

在最近修改一个很老的 Ant Design Pro 后台管理系统时，我遇到一个在 服务器 上运行时出现的严重问题，而本地环境下始终运行正常。这篇文章将详细记录该问题的排查过程及最终的解决方案，希望对大家在处理类似问题时有所帮助。

一、问题描述

当我在 服务器 上部署并运行项目时，出现了如下错误：

fatal - Error: Cannot find module './user/login' from '/home/admin/src/pages'
...
code: 'MODULE_NOT_FOUND'

找不到模块? 最开始，我以为是代码配置问题，于是重点检查了 config/routes 中的路由设置，修改了路由的 path、name 和 component 属性，检查了src/pages/user/login文件,尝试了相对路径和绝对路径，但问题依旧存在。在服务器上无论是执行 npm run dev 还是 npm run build，都抛出了同样的错误。

二、问题根源

在排查无果后，我决定去 GitHub 仓库上查看项目的文件结构，结果发现问题的根源：文件夹名称的大小写不一致。

在 GitHub 仓库中，相关路径为：src/User/login（大写的 User）
而在我的本地开发环境中，该路径为：src/user/login（小写的 user）

由于 macOS 和 Windows 的文件系统对文件名大小写不敏感，因此本地运行项目时没有任何问题。然而，Linux 系统是大小写敏感的，所以在服务器上部署时，Git 拉取的文件夹名为 User，但代码中引入的路径却是 user。这种大小写不匹配导致了模块无法找到的错误。

三、错误的原因

在某次修改中，不仅更改了文件夹名称（从大写 User 改为小写 user），同时还进行了其他代码修改。由于git本身在默认情况下是大小写敏感的，但是在git init 或者git clone 的时候，如果操作系统的文件系统是大小写不敏感的，Git 会自动设置 core.ignoreCase=true，使其在这种文件系统上工作时忽略大小写变化。，因此它并未追踪到这次大小写的变化，导致提交后远程仓库中的文件夹名称没有变化。而在服务器上（Linux 系统），文件名的大小写敏感性造成了问题的暴露。

四、解决方案

方案 1：通过 Git 强制更改文件名

由于 Git 默认不区分文件名大小写，我们可以通过重命名文件来强制 Git 识别文件名变化：

git mv page/User/index.tsx page/temp/temp.tsx
git mv page/temp/temp.tsx page/user/index.tsx

通过这个过程，我们先把文件临时重命名为 temp.tsx，然后再重命名为正确的小写路径 user/index.tsx，这可以确保 Git 能够识别大小写变动。

方案 2：修改 Git 配置以区分大小写

我们还可以通过修改 Git 的配置，让它在本地环境中也能够区分大小写。步骤如下：

修改 Git 配置，确保它不忽略文件名的大小写变化：
```
git config core.ignorecase false
```
从 Git 的缓存中移除旧的（大写的）文件路径：
```
git rm -r --cached page/User/index.tsx
```

重新将正确的小写文件路径加入 Git 并提交：

git add page/user/index.tsx
git commit -m "Fix case sensitivity issue for User directory"
git push origin main

总结

这次问题的根源在于 Git 默认的文件名大小写不敏感行为，以及不同操作系统对文件名大小写处理的差异。对于在 macOS 或 Windows 上开发，而在 Linux 服务器上部署的项目，文件名大小写的统一 极为重要。特别是在 Git 提交代码时，应该注意操作系统和 Git 的文件名处理方式。

通过这次排查，我学到了以下几点经验：

注意文件名大小写：尤其在跨平台开发中，确保所有文件名在本地和远程环境中保持一致。
Git 追踪文件名大小写变化：必要时可以通过强制重命名或修改 Git 配置来解决大小写敏感问题。

希望这次记录能帮助到遇到类似问题的开发者，也提醒大家在代码提交时注意文件名大小写的细节。

微信公众号