写出一份真实、细致、可落地的gitignore实战指南，把我自己这几年在项目里踩过的坑、用过的套路、排查过的怪问题都揉进去，希望能一次讲透。
很多 Git 新手都会遇到一个特别头疼的画面：辛辛苦苦写好的代码，一提交，项目里全是乱七八糟的文件。node_modules、target、__pycache__、.idea、*.log、本地配置……全被当成正经东西推上去了。明明工作区里看着挺干净，怎么一到仓库里就变垃圾场？我早些年还真干过把.idea和node_modules一起 push 上去的蠢事，结果队友每次拉代码都卡半天，IDE 设置也互相覆盖，简直灾难。今天这篇就来聊聊.gitignore，这个让 Git 学会“选择性失忆”的配置文件，从原理到语法，再到实操和排坑，一次说个明白。
1. 先搞清楚：Git 为什么会“记性太好”
1.1 工作区、暂存区、版本库的三层记忆
要理解.gitignore是干嘛的，得先看 Git 的数据流向。我们平时敲代码的地方是工作区，相当于你的草稿纸；git add之后文件进入暂存区，好比是把要交的作业先放到一个透明文件夹里；git commit之后写入版本库，才算正式归档。
.gitignore管的就是“哪些草稿纸上的内容永远不要进入那个透明文件夹”。它本质上是一份黑名单规则，告诉 Git 哪些文件不需要被追踪、不需要被提交。注意这里的用词——不需要被追踪（untracked），意味着这个文件对于 Git 来说是透明的，它不会出现在git status里，也不会被误git add .带进去。
很多人刚开始没理解这层，以为.gitignore只是“隐藏文件列表”，其实搞反了。只要文件已经被 Git 追踪，也就是你曾经git add过，甚至已经提交到了版本库，那.gitignore对它就完全无效。这个点我在第 4 节会重点展开，因为十个人里有八个说“我的.gitignore没用”，十有八九都栽在这。
1.2 忽略规则真正生效的节点
我习惯把这三个区域想成一套安检流程：
- 工作区里的文件相当于装在包里的物品；
git add .是过安检机；git commit是登记行李托运。
.gitignore就贴在安检机入口，上面写着一排字：“以下物品直接放行，不用检查。”规则匹配上的文件，连安检机都不会看一眼，自然更不可能被托运。但有一种情况例外——如果这件物品之前已经被托运过，并且登记在案了（已追踪），那安检口就算贴了规则也没用，因为它已经进入系统档案了，下次更新照样会被检查。
这时候你会遇到一个反直觉的现象：明明在.gitignore里写了target/，可是工作区里的target目录还是出现在git status里。别慌，不是规则写错了，是文件早就被追踪了。后面会讲最新的解决方案。
1.3.gitignore相关的三个不同层级
Git 里能用来忽略文件的机制其实有三个位置，很多人只知道一个：
| 位置 | 生效范围 | 使用场景 |
|---|---|---|
项目根目录的.gitignore | 整个项目 | 通用规则、构建产物、依赖目录 |
子目录下的.gitignore | 该目录及其子目录 | 局部特殊规则、项目嵌套 |
.git/info/exclude | 仅本地仓库 | 个人本地配置，不随仓库分享 |
三者优先级有点微妙：越靠近子目录的规则越优先，子目录的.gitignore能覆盖根目录的规则。.git/info/exclude则只作用于当前仓库的本地环境，适合放一些“只有自己电脑上才有的东西”，比如本机的 IDE 私密配置、个人临时脚本。因为它是写在.git目录里的，所以永远不会被提交，也不会推给同事。
这里给个建议：能写进根目录.gitignore的规则，尽量写进根目录。不要大量使用.git/info/exclude，因为一旦换电脑或者克隆新仓库，全部失效，也不利于团队统一规范。那玩意儿更适合那些你不希望队友知道也不要他们遵守的私人文件规则。
2. 规则语法：一行模式对应一类问题
2.1 按名字、路径与目录进行三种不同的匹配
.gitignore的行可以粗略分三类：直接写名字、写路径、写目录。
- 直接写名字：
config.log，匹配项目下任意层级同名的文件或目录。 - 写路径：
/dist/，斜杠开头表示相对于.gitignore所在目录的根路径，只匹配根目录下的dist。 - 写目录：
build/，末尾带斜杠，只匹配目录而不是同名文件。
这是最容易犯迷糊的地方。举个例子，规则foo.log匹配src/foo.log、bar/foo.log，任何层级的foo.log全进黑名单。而/foo.log只匹配仓库根目录下的那个foo.log，如果你在src/下面放了一个foo.log，它该出现还是会出现。
末尾斜杠也很关键：build/忽略的是所有名为build的目录，但如果恰好有一个文件叫build，它就管不着。反过来说，如果你写build不带斜杠，那不管文件还是目录只要叫这名都忽略。实战里大部分场景我们想忽略的是整个目录，所以我的习惯是写带斜杠的目录形式，语义更清楚。
2.2 通配符：*、?、[]、**的语义差别
.gitignore支持的通配符和 shell 很像，但有几个细节值得单独说：
*匹配任意多个字符，但它在 Git 的实现里不跨越目录层级。也就是说*.log能匹配a.log，但匹配不了logs/a.log。如果想跨目录匹配任意层级的.log文件，得用**/*.log。?匹配单个字符。比如test?.py会匹配test1.py、testA.py，但不匹配test10.py，因为那有两个字符。[]是字符集合，[abc].txt匹配a.txt、b.txt、c.txt；[0-9].log匹配单个数字开头的.log文件。**是进阶课代表：logs/**/debug.log会匹配logs/debug.log、logs/x/debug.log、logs/x/y/debug.log；**/temp匹配任意层级下名为temp的文件或目录。
有一回我排查同事的规则，发现他写了*.min.js，但项目里是static/js/vendor.min.js，一直没被忽略，他以为 Git 出 bug 了。其实原因就是*不跨目录，改成**/*.min.js立刻生效。这个细节不实操过一遍很容易忽略。
2.3 取反规则!的优先级和“死区”问题
!感叹号开头代表“排除忽略”，也就是白名单逻辑。典型用法是先忽略这一类，再放行其中某个特定文件，比如：
*.log !important.log意思是所有.log都忽略，但important.log要保留追踪。听起来很简单，但这里有一个很阴的坑：如果某个文件所在的目录被忽略了，那针对该文件的取反规则不会生效。Git 剑走偏锋，不会为了验证文件而穿透已经忽略的目录。
举例说明：
build/ !build/keep.txt这段规则表面上想“忽略 build 目录但保留 keep.txt”，实际效果是build/keep.txt照样被忽略，因为整个build目录已经在忽略范围内，Git 根本不会进去扫描。正确的写法是：
build/* !build/keep.txt先忽略build目录下所有内容，再放行keep.txt，这样父目录没被彻底屏蔽，文件级取反才有效。我最初在这个问题上反复试了几次才摸清规律，规则之间的优先级不是全局的，而是层层递进的，底层目录不能是“失明状态”。
2.4 空行、注释与行尾空格的处理
严格来说这不算语法，但团队里经常因为格式问题导致规则失效。.gitignore里以#开头的行是注释，空行什么都不匹配，纯粹为了方便阅读分区。可是如果一行里有行尾空格，有些编辑器会自动“修掉”，有些则保留，空格也会作为文件名的一部分参与匹配。
我见过最奇葩的一个 bug：规则文件从 Windows 拷贝到 Linux，行尾从CRLF变成LF，或者反过来，结果某些规则直接失效。Git 对.gitignore的行尾处理是相对宽容的，但最好统一用LF。你在.gitattributes里可以声明/.gitignore text eol=lf，从源头避免这个坑，后面家常便饭的问题就不至于莫名其妙爆发。
3. 从零写一份能用的.gitignore
3.1 先盘点项目里的“垃圾文件类型”
动手写规则之前，别急着一顿抄模板。先想清楚你的项目里会产生哪几类不需要进仓库的东西。我总结下来就四类：
- 依赖目录：
node_modules、vendor、target、site-packages这类能通过包管理器或构建脚本重新生成的内容。 - 编译产物：
.class、.pyc、.o、.dll、.exe、dist、build、*.egg-info这种转一下就能再出来的东西。 - 本地配置：
.env（里面时常有密钥和数据库地址）、.idea、.vscode（除非团队统一编码规范需要提交配置）、.DS_Store（macOS 的目录元数据）。 - 日志与临时文件：
*.log、*.tmp、*.cache、*.pid、*.swp。
按这个分类去写，基本上不会漏太多。更重要的是，你得能回答自己一个问题：这些文件如果丢了，能不能通过一条命令、一次构建自动恢复?能，那它就该被忽略；不能，那正是仓库必须承载的东西，别乱忽略。
3.2 前端和后端项目的最常用模板
此前端项目为例，一份比较稳妥的.gitignore长这样，我帮你拆解每一段的作用：
# 依赖目录 /node_modules /vendor # 构建产物 /dist /build *.tsbuildinfo # 测试与覆盖率 /coverage .nyc_output *.lcov # 日志 logs/ *.log npm-debug.log* # 本地环境 .env .env.local .env.*.local # 编辑器 .idea/ .vscode/* !.vscode/extensions.json .DS_Store注意我们对.vscode的处理是“忽略里面所有东西，但保留extensions.json”——这用来同步团队推荐的插件列表。这个写法用到前面说的目录忽略加取反的技巧。.env类文件一律不进仓库，避免密钥泄露。如果你的项目需要提交一个env.example作为模板，那.env.example不在忽略范围内，正常提交即可。
后端项目一般还要加__pycache__/、*.py[cod]、.pytest_cache/、.mypy_cache/、target/、*.jar、*.war之类。核心思路一致，依赖和编译产物全挡在门外。
3.3 全局配置还是项目内配置
有些文件是跨项目的，比如.DS_Store、Thumbs.db、*.swp，每个项目都写一遍有点烦。Git 支持全局忽略文件，路径因人而异，在 Linux/macOS 上通常是~/.config/git/ignore，Windows 上可能是C:/Users/你的名字/.config/git/ignore。用git config --global core.excludesFile ~/.config/git/ignore指定即可。
可是全局配置有个隐患——它只在你的机器上生效。如果团队里另一个同事没配，照样会把.DS_Store或Thumbs.db提交进仓库。所以我建议把跨平台的通用心得写进全局配置，把项目相关的规则写进仓库内的.gitignore。这份文件本身要被提交，所有成员共享，这才是真正的团队规范落地。
4. 实战排查：为什么.gitignore失灵了
4.1 文件已被追踪导致的规则失效
这是最常见的“鬼故事”。你明明在.gitignore里写了node_modules/，但git status依然显示一堆node_modules下的文件状态变化。原因不复杂——在写入规则之前，这些文件已经被git add过，甚至已经推进仓库了。
Git 的规则只作用于未被追踪的文件。已经进入暂存区或版本库的文件，属于“合法公民”，gitignore管不着。解决方法是先把它们从 Git 的追踪列表里移除，但保留在本地。我常用的命令是：
git rm -r --cached . # 从暂存区移除所有文件，但保留本地工作区 git add . git commit -m "chore: 应用 .gitignore 规则，移除本不应追踪的文件"--cached是关键，它只移除 Git 索引里的追踪记录，不会真的把你本地的文件删掉。日志文件、依赖目录、临时配置一个都不会少，但 Git 从此睁一只眼闭一只眼。如果你只想移除某个路径，替换.为具体路径即可，比如git rm -r --cached node_modules。
这个操作做完后最好马上提交一次，否则你会在git status里看到海量的“deleted”记录，很容易误以为自己把文件搞没了。第一次做记得深呼吸，真的没删，只是 Git 决定不记了。
4.2 匹配优先级问题导致规则不生效或误伤
有时候规则本身没错，但两条规则打架了。最典型的例子：
*.log !*.log后一行把前行完全覆盖，结果所有日志文件都不被忽略。如果你在不同层级放了多个.gitignore，子目录规则优先于父目录规则，这个优先级是 Git 的硬性规定，不看书写顺序。我见过最折腾的一次排障，就是根目录忽略dist/，但src/frontend/.gitignore里写了!dist/keep.txt，最后所有dist下文件全被忽略，误伤期望保留的文件。
排查这种问题没有捷径，最有效的办法是git check-ignore -v <file>。这个命令会告诉你哪条规则匹配了这个文件，来自哪个文件的哪一行，属于哪个优先级。比如：
git check-ignore -v src/frontend/dist/keep.txt输出会显示.gitignore:2:build/ src/frontend/dist/keep.txt这类信息。看到具体来源后，你就能判断是该改根规则还是该挪走子规则。别靠肉眼猜，除非你想把半小时耗在瞪眼上。
4.3 大文件和二进制文件拦截
Git 本身并没有强硬的“禁止大文件”功能，但很多团队在git commit之前加了钩子脚本来拦大文件。如果你碰到“无法提交大文件”或“推送被拒”的问题，通常是因为仓库托管平台限制了单个文件大小（比如 GitHub 限制 100MB，Gitee 也一样有上限）。这时可以通过.gitignore把可能产生大文件的目录提前排除，比如模型权重文件*.h5、*.pkl、*.pt、model.bin。
如果你确实需要版本管理大文件，那得用 Git LFS（Large File Storage），把大文件指针存进仓库，实际内容存到 LFS 服务器。这和.gitignore是两个维度的方案，不是非此即彼的替代关系。我的建议是：构建产物和本地生成的模型文件一律进.gitignore，真正需要共享的数据文件走 LFS。
# 常见大文件忽略模式 *.h5 *.hdf5 *.pkl *.pt *.pth *.onnx *.bin *.model data/raw/4.4 IDE、分支合并和缓存问题导致规则被“穿透”
有时候.gitignore并没有失效，是你操作流程里引入了意想不到的文件。拿 IDE 举例：IDEA 重新导入项目或者执行“Git 更新”时，如果它发现某个文件进了忽略列表，通常会自动标记为忽略状态。但它的本地历史、缓存文件可能放在系统临时目录里，偶尔会从代码扫描里冒出来，看着像“穿透”了规则，其实只是显示层面的干扰。
还有另一个场景是合并分支。假设master分支上之前提交了一个不应该提交的config.ini，你在新分支的.gitignore里加上了规则，但合并的时候，旧的追踪记录还在，config.ini照样被合并进目标分支。这种问题唯一的根治办法还是git rm --cached，并且要做在整个仓库层面，不是某一个分支。我一般在合并这类“历史遗留问题”时，专门开一个清理提交，把所有本不该存在的文件一次性移除，再提交.gitignore，这样后续分支就不会继续携带这些垃圾文件。
5. 让“选择性失忆”成为团队习惯
5.1 模板库与规范化
.gitignore不是写一次就完事的。项目换了一个构建工具，新增了一种日志文件，甚至是团队换了一种操作系统，规则都要跟着变。我的做法是维护一个内部模板库，按语言分类：Python.gitignore、Node.gitignore、Java.gitignore、Unity.gitignore等，新项目起步时复制过来，再根据具体项目调整几行就行。
GitHub 官方有个gitignore仓库，维护了一套非常详尽的模板集合，直接去参考比自己从零开始写省事太多了。但套模板的时候一定要做减法，不要一把梭全搬过来。别人模板里的规则不一定适配你的项目，规则过多反而容易覆盖掉该提交的文件。我记得有次我用某个大而全的模板，结果把项目里的Dockerfile都差一点忽略掉，幸好提交前检查了git status，不然真的会出事故。
5.2 提交前强制检查 Git 状态
很多人写.gitignore时是把它当作文档来写的，写完就推。我建议把提交前检查git status养成肌肉记忆。我自己的流程是：
git status git diff # 确认改动的代码本身没问题 git status --ignored --short # 看一下被忽略的文件是否符合预期 git add . git commit第四个命令很多人没注意过，git status --ignored会单独列出所有被忽略规则挡掉的文件。提交前瞄一眼这个清单，如果发现某个文件不该被忽略，还能及时调整规则，不至于把问题留给下一次 push。这相当于给“选择性失忆”加了一个回看按钮，特别推荐。
5.3 我踩过最深的坑和最终建议
回看几年，我踩过的坑汇总一下，其实就几条：
.gitignore不是安全机制，不是保险箱。它只是屏蔽了 Git 的视野，文件的敏感内容如果已经被提交过，历史记录里还留着，清理规则不能抹去历史。要让敏感信息彻底消失，需要改历史或者用专门工具，这是另一个大话题。- 不要过度忽略。有些资料文件、配置模板、文档生成脚本，虽然看起来“可自动生成”，但如果生成环境不一致，反而该提交原始资源。忽略的快感会让人上瘾，但仓库真正的价值是完整可构建的状态记录，不是只保留源码的“瘦身秀”。
- 忽略规则要定期维护。每引入一个新的框架或工具，先瞄一眼它会不会生成一堆本地文件，平时多注意
git status里那些冒出来的怪文件名，随手加进规则。一次维护省半年的事后清洗。
.gitignore这门手艺，看着只是几行规则，实际上把 Git 的使用边界划清楚了。你越早学会，就越少经历“项目突然变成垃圾场”的绝望。而且这套思维方式不仅适用于 Git，也适用于所有需要“选择性记录”的系统——你得先想清楚什么应该被持久保存，什么只是临时产物，才不会让真正有价值的东西被海量噪音淹没。我个人现在新建任何项目，第一件事就是写好.gitignore，第二件事是初始化提交，这两步做完，心里才踏实。
