企业官网建设流程全解析

打开仓库执行git status，屏幕干干净净——但你明明刚把README.md改成了readme.md。是不是有点慌？再一看，文件还在，名字也确实变了，可 Git 就是假装什么都没发生。如果你在团队里遇到过"为什么我改了文件名大小写，提交记录里却只有一个变化"，或者"同一个文件在 Mac 上正常、在 Windows 上突然冒出两份"这种灵异事件，那大概率就是撞上了 Git 的大小写陷阱。

这问题不罕见，但它坑人的地方在于：不是每次都出现，也不是所有人都会遇到。一旦遇到，很多人的第一反应是怀疑自己手滑了，然后怀疑 Git 坏了，最后才意识到是文件系统、操作系统和 Git 默认配置三方之间的"默契"出了问题。这篇文把来龙去脉讲透，再把常用解法整理成几套方案，你照着操作就能处理干净，顺带把以后怎么避免也讲清楚。

适合人群：用过 Git 但没深究过文件大小写机制的人，以及团队里经常跨 Windows / macOS / Linux 传代码的人。文中的命令我都实际跑过，Git 2.30 以上的版本都适用，部分命令在更老的版本上也兼容。

1. 这个坑长什么样：三种典型现场

1.1 现场一：改名后 Git 表示"无事发生"

我在 Windows 上做过一次测试，步骤很朴素：新建一个仓库，README.md提交一次，然后右键重命名为readme.md，回到终端执行git status，结果输出只有nothing to commit, working tree clean。我当时第一反应是"我是不是改错文件了"，又回去看了一眼资源管理器，文件名确实是小写开头。后来才知道，Git 的core.ignorecase默认值在 Windows 和 macOS 上通常是 true，它会直接把工作区里的大小写变化忽略掉，于是你的改名在 Git 眼里就跟没发生一样。

但诡异的地方在于：文件确实已经改名了。如果你这时候直接git add .再提交，Git 并不会把变更记录下来——它在对比索引和工作区时发现"这两个名字只是大小写不同，那就当成同一个文件"，于是一律跳过。结果是：你的本地文件名已经变了，仓库里的记录却还是README.md。等你哪天把这个分支推到远端，别人 clone 下来看到的文件名又变回大写的README.md，本地和远端完全不一致，谁都没做错什么，但就是对不上。

1.2 现场二：同一个文件在另一边"分身"

比"无事发生"更迷惑的，是跨平台协作时出现的双胞胎文件。举个例子：团队里有人在 Linux 上把README.md改成了readme.md（Linux 的 ext4 文件系统严格区分大小写，Git 也认），正常提交、推送。你作为 Windows 用户拉下这个提交，Git 在 checkout 时发现索引里有个readme.md，而工作区里已经存在一个README.md的旧文件——因为 NTFS 默认不区分大小写，这两个名字在磁盘上对应同一个文件，但 Git 不这么认为。于是目录里可能同时留下两个名字一眼看去一模一样、只有大小写不同的文件，更严重的会直接报error: invalid path或 checkout 冲突。

这种分身在项目里非常阴险：你搜索文件时看到两个名字，改一个另一个不变，IDE 还会提示"文件重复"。如果当时没注意，两个都提交了，仓库里就永久留下了两份内容几乎相同的文件，后续每次合并都有人改错、内容漂移，最后只能靠人工比对去清洗。我见过一个仓库因为这种情况浪费了一整个迭代的时间，想想都觉得不值得。

1.3 现场三：clone 完整，checkout 却报错

还有一种情况更容易出现在打包和部署环节。CI 服务器大多是 Linux，严格区分大小写，所以只要项目里同时存在README.md和readme.md，Linux 上也能正常共存。但这个仓库被 Windows 机器 clone 时，两个路径在 NTFS 上指向同一个文件，Git 想同时检出两个路径，磁盘不同意，轻则只检出其中一个，重则 checkout 直接失败，报一长串错误。遇到这种报错，新手往往以为是网络问题或者仓库损坏了，实际上就是大小写冲突在文件系统层面被拦住了，和网络没有任何关系。

2. 为什么 Git 会"大小写不敏感"：core.ignorecase 与文件系统的三角关系

2.1 Git 内部其实一直区分大小写

先把结论摆出来：Git 的核心存储层从来都是严格区分大小写的。仓库里的对象数据库（.git/objects）以哈希值命名文件，根本不存在"大小写歧义"；索引文件（index）里记录的路径也保留原始大小写，README.md和readme.md在索引里是两个完全不同的路径字符串。Git 判断"这个路径是否存在"时，本质上是在做字符串比较，所以它内部从来都是敏感的。

那为什么表现上好像不敏感？因为 Git 为了适配工作区效率，加入了"猜测"逻辑：它拿着索引里的路径去文件系统上做对比时，会先问一句"这两个文件实际上是不是同一个？"回答这个问题的不是 Git 自己，而是操作系统。Windows 的 API 告诉你"它们大小写不敏感"，Git 就信了。这就是整个问题的根源：Git 内部的逻辑是大小写敏感的，但它对外必须适配文件系统的"性格"，而不同平台的"性格"截然不同。

2.2 真正的罪魁祸首是文件系统

我把常见文件系统的"性格"整理成一张表，方便你对照：

注意"敏感"和"保留"是两回事。NTFS 和 APFS 虽然不敏感，但会保留你写入时的大小写；也就是说，你把README.md改成readme.md，文件系统认它们是同一个文件，但同时记住新名字。真正的坑点在"不敏感"上：你问文件系统"是否存在 readme.md"，它只要找到一个大小写匹配不上的README.md也会回答"存在"。Git 的文件状态判断因此失灵，无法区分"这到底是一次真实的大小写变更，还是什么都没变"。

2.3 core.ignorecase 这个配置到底在做什么

Git 在首次初始化仓库时会检测当前文件系统的特征，然后写下一个配置项core.ignorecase。Windows 和 macOS 上默认是 true，Linux 上默认是 false。这个配置影响的不只是提交判断，还包括 checkout、merge、diff 等几乎所有涉及路径的操作。

当core.ignorecase=true时，Git 会"忽略大小写地判断路径是否存在"，于是README.md → readme.md被视为"同一个文件，没变化"。这里有个很容易误解的点：很多人以为把这个配置改成false就能立刻看到变化，实操中确实能看到git status突然冒出一堆deleted: README.md和new file: readme.md，但这时候你反而要小心——false的意思是告诉 Git "不要信任文件系统的大小写行为，严格按字符串比较"，它会把工作区里所有路径逐一严格对比，可能把所有"看起来正常"的大小写不一致项全部抖出来，处理不好就是一场事故。我建议：定位问题、排查问题时可以临时改成false，但别长期开着，尤其在 Windows 上，它会让你日常操作产生大量噪音。

2.4 为什么"删了重新加"就能成功

"直接把文件删掉再新建"是网上流传最广的解法，原理其实很简单：git rm README.md会把旧路径从索引里移除，随后git add readme.md又把新路径加回去，索引里完整走了一遍"删除旧、添加新"的过程，Git 在提交时看到的就是两个明确的操作。它绕开了"改名"这种需要靠文件系统回答"是不是同一个"的暧昧逻辑，自然就能成功。这也是它最稳的原因——不依赖任何平台的文件系统行为，在 Windows、macOS、Linux 上都一样可靠。

3. 实操：一次完整的大小写改名到底该怎么走

3.1 动手前先检查三件事

先说检查顺序，省得你改了半天发现改错分支或者根本不在仓库里。第一步，确认当前目录确实是仓库目录，执行git rev-parse --show-toplevel，如果报fatal: not a git repository (or any of the parent directories): .git，说明你站的地方不对，先进到正确的目录再说。这条错误其实和大小写无关，纯粹是"不在仓库里"，但排查问题时很容易遇到，顺手列出来。

第二步，确认当前分支状态是干净的——不是必须，但推荐。git status里如果有未提交的改动，先处理完再改名，不然改名产生的变更和已有改动混在一起，后面排查起来很难受。

第三步，查看当前仓库的core.ignorecase值：

git config core.ignorecase

输出true基本可以断定你会踩坑；输出false的话，直接git mv大概率能一次成功。顺便也看一眼当前分支：git branch --show-current，避免在错误分支上操作。

3.2 方案A：git mv 两步法（最稳）

如果你的系统是 Linux，或者core.ignorecase已经是false，一行命令就能搞定：

git mv README.md readme.md git status

确认状态里显示的是renamed: README.md -> readme.md，然后正常提交即可。但如果你的系统在 Windows 上并且core.ignorecase是 true，直接执行上面这条会报fatal: destination exists，或者干脆提示 nothing to do，因为 Git 认为源和目标是同一个文件。

这时候用两步法绕过去：先把文件改成一个临时名字，再改回目标名字：

git mv README.md README.tmp git mv README.tmp readme.md git status

两步操作都发生在索引里，临时名字README.tmp跟源、目标都不同，Git 无法产生任何歧义，所以能稳稳地完成改名。实测在 Windows + Git 2.40 上，这套流程的输出是标准的renamed状态，提交后仓库记录干净。临时名可以随便起，只要大小写和最终目标不一样就行，我习惯用.tmp后缀，一眼就知道是过渡文件。

提交时建议写清楚这次改名的意图，例如：

git commit -m "chore: rename README.md to readme.md for consistency"

以后翻历史记录的时候，你能一眼看出这次提交做了什么，而不是对着一条模糊的 "fix" 发愣。

3.3 方案B：git rm --cached 后重新添加

如果你的文件已经被手动改过名（也就是说你先用资源管理器或命令行改了，然后才想起来 Git 的事），用两步法可能会来不及，因为工作区里的文件名已经变了。这种情况下就走"删除索引 + 重新添加"路线：

git rm --cached README.md git add readme.md git commit -m "chore: rename README.md to readme.md"

注意这里用的是--cached，意思是只把文件从索引里移除，不触碰磁盘上的文件。如果你漏掉--cached直接git rm，Windows 上可能因为文件正被占用或者名字歧义直接失败，最坏情况是把磁盘文件也删了，那就真的麻烦了。执行完git add readme.md后，索引里就是"旧的没了、新的有了"，提交即可。这种方式不依赖文件系统行为，是最通用的兜底方案，我建议把它记熟。

3.4 方案C：直接调整 core.ignorecase

如果你确定自己就是要在 Windows 上长期做大写敏感的严格管理，可以把配置改成false：

git config core.ignorecase false

改完之后，git status会立刻把所有"索引路径与工作区路径大小写不一致"的差异暴露出来，你会看到大量删除/新增条目。这时逐一确认每个条目是不是你想要的改名，再统一提交。我不建议团队里的所有人都改这个配置——它会改变每个人的日常视图，风险很大。更合理的用法是：只在出问题的那台机器、那个仓库上临时改，处理完再改回true。改回方式：

git config core.ignorecase true

记住，这个配置是跟着仓库走的（写在.git/config里），不会影响其他仓库，所以临时改动不用担心"污染"全局设置。

3.5 提交时用 --amend 修正上一条错误提交

如果你已经把"看起来啥都没改"的空提交提交上去了，或者提交信息写错了，最常用的修正手段是git commit --amend。它有几种用法，挑最实用的说：

git commit --amend # 修改提交信息，进入编辑器 git commit --amend -m "chore: rename README.md to readme.md" # 直接覆盖提交信息 git commit --amend --no-edit # 不改信息，把新的暂存内容并入上一条提交

但这里要给你一个忠告：--amend本质是重写最近一次提交的哈希。如果这个提交已经推送到远端且被别人拉取过，amend 之后本地与远端历史不一致，下一次 push 会被拒绝，非得git push --force才能覆盖。在团队仓库里 force push 是高风险操作，能不用就不用。正确做法是：觉察到"我提了个无效提交"时，趁它还没推上去，马上 amend；如果已经推了，那就老老实实补一个新提交说明情况，不要在共享分支上搞历史重写。

4. 跨团队协作时的高危场景与排查

4.1 高危场景清单

大小写问题在单机单平台下最多是个"奇怪现象"，一旦进入多人协作和跨平台环节，它就变成真正的坑。我按风险从高到低列几个典型场景：

第一，Windows 与 Linux 混用的仓库。Linux 上正常的小写改名提交，Windows 拉下来要么报 checkout 错误，要么直接留下双胞胎文件，这是最常见的高危场景。

第二，移动存储与跨设备。U盘、移动硬盘常是 exFAT，不区分大小写。你把仓库放在 U 盘上跑 Git，行为上限完全取决于设备格式，换个设备格式不同，Git 判断也跟着变，同一套操作在两个设备上结果可能完全不同。

第三，自动化脚本里的路径引用。CI 脚本、Dockerfile、部署脚本里写死README.md还是readme.md，只要大小写不一致，Linux 环境立刻报找不到文件，而在 Windows 本地调试时一点问题都没有，属于"本地没事、上线就挂"的典型。

第四，包管理器与构建工具的缓存。某些工具会按文件名区分缓存，大小写变化可能导致缓存命中失败或重建，连锁引发奇怪的构建问题。这一条容易被忽略，排查起来也麻烦，因为报错信息里往往不会直接提到文件名大小写。

4.2 典型问题速查表

我把实操中最常见的现象和对应处理整理成下表：

这张表里的处理方式都是验证过能直接落地的，但有个前提：操作前先备份或者确认改动集中在单一目录，不要一上来就大面积清理。文件系统层面的问题，操作得越急，越容易把仓库搞得更乱。

4.3 我踩过的坑与排查思路

说一个我实际经历过的例子。有次接手一个跨平台项目，仓库里出现了README.MD和readme.md两个文件，内容一模一样但后续更新时分叉了。团队里用 Windows 的同事根本不知道该改哪个，用 macOS 的同事发现自己在编辑器里打开的是同一个文件，用 Linux 的同事则在合并时被反复要求处理冲突。最后我是靠下面的命令把所有索引路径拉出来对比，才确认重复的来源：

git ls-files | grep -i readme

这条命令会把仓库里所有名字含 readme（不分大小写）的路径列出来，一眼就能看出是否存在重复。找到重复后，我选定唯一标准命名（全小写），把另一个用git rm删掉，提交，再让所有同事重新 pull。那次之后我就立了规矩：这个仓库里所有文档统一小写命名，提交前必须跑一遍上面的 grep 检查。现在回想起来，这次事故本来完全可以靠一条命令提前避免，但因为没人知道"大小写会被 Git 微妙地处理"，硬是多花了两天的人工对账时间。

5. 把坑提前填掉：习惯与规范建议

5.1 改名一律走 git mv

我见过太多人习惯在文件管理器里重命名，然后回终端git add .一把梭。在大小写不敏感的系统上，这就是问题的起点。给自己立一个最简单的规矩：在 Git 仓库里改文件路径，一律用git mv，不要用系统重命名。git mv会同时更新工作区和索引，保证 Git 全程知道你在做什么。要是已经用系统改了名，也别慌，回到终端用 3.3 的兜底流程补上即可。规则简单，才能坚持执行。

5.2 给 Git 装上"大小写警报"

日常开发中，可以用一个小技巧提前发现问题：每次觉得"好像有重复文件"时，立刻跑git ls-files | grep -i <关键字>。如果输出里出现多个仅大小写不同的路径，说明仓库里已经有隐患，趁早清理。另外，如果你用的是 IDE，可以在设置里开启"文件名大小写敏感"的显示高亮，这样资源管理器视图里出现重复文件时会更显眼。不过这些都不是自动的，真正的防线还是在提交前多看一眼git status，尤其是在跨平台团队里。

5.3 团队命名规范与 CI 检查

跨平台团队最该做的一件事，是把"文件命名统一"写进规范。我的建议是：所有新文件一律小写英文命名，单词间用连字符，不要用驼峰，不要用大写扩展名。这套规则在 Linux、Windows、macOS 上都不会产生歧义。更进一步，可以在 CI 里加一条 Shell 检查，扫描索引路径中是否存在大小写重复：

git ls-files | sort -f | uniq -di

有重复输出就视为检查失败，阻止合并。这是目前我看到的最简单、最便宜的护栏，比事后清理省无数倍的时间。如果你用的 CI 不支持直接跑 Shell，也可以在代码规范工具里自定义一个 lint 规则，思路完全相同。关键是让"大小写重复"在合并前就被机器拦住，而不是靠人眼去发现。

5.4 最后的补救手段：reset 与重新同步

如果仓库已经被大小写问题搞得很乱，又不想一个个改，可以考虑局部重置。前提是这个分支只有你自己在用，或者你确认可以安全丢弃最新几次提交。常见做法是git reset --soft HEAD~n回退若干提交，重新整理后一次提交；更激进的是git reset --hard，这会丢掉工作区所有未提交改动，务必谨慎使用。我个人的习惯是：宁可先git branch backup-xxx建一个备份分支，再动手清理，清理完确认无误再删备份，给自己留一条退路。毕竟仓库历史是你和团队共同的资产，多一道保险总比事后后悔强。

最后再说一点我自己的体会。大小写问题在 Git 里之所以难缠，不是因为它技术多深，而是因为它藏在"默认配置 + 平台差异 + 操作习惯"三层巧合之下，平时完全不显形，偶尔出来咬你一口。我踩过几次坑之后，已经养成了三个固定动作：改名必用git mv、看到"无事发生"立刻查core.ignorecase、每次提交前用git ls-files扫一遍重复路径。这三个动作成本极低，但基本能覆盖九成以上的大小写事故。如果你现在正被这个坑折磨，先按第 3 节的两步法把当前问题解决掉，再花十分钟把 5.3 的 CI 检查加上，一劳永逸。