.gitignore 怎么写：Git 忽略文件规则与常见模板

.gitignore 是放在 Git 仓库根目录下的一个纯文本文件，里面的每一行是一条忽略规则，告诉 Git 哪些文件不纳入版本管理。用完它的关键是记住一句话：规则只对「还没被跟踪」的文件生效，已经提交过的文件要先用 git rm --cached 解除跟踪。把临时文件、配置密钥、构建产物挡在仓库外，是 Git 使用的基本功。

.gitignore 是什么、放在哪里

Git 会跟踪项目目录里的所有文件变化，但有些文件根本不该进仓库：程序运行产生的日志、构建生成的打包产物、本机私有的配置文件、系统的自动生成文件。.gitignore 就是给 Git 的「黑名单」，写进去的文件会被 Git 自动跳过，不参与提交。

它必须放在仓库根目录才能作用于整个项目，文件名严格写成 .gitignore（开头有个点）。用 VS Code 或记事本都能编辑，保存为 UTF-8 编码即可。Git 官方文档对规则有完整定义，本文讲的是最常用的那一部分。

基础语法：一行一条规则

| 写法 | 含义 | 示例 | |------|------|------| | # 开头 | 注释，方便别人看懂规则 | # 忽略构建产物 | | 文件名 | 忽略所有目录下同名文件 | secrets.txt | | /文件名 | 只忽略仓库根目录下的该文件 | /config.local.json | | 目录名/ | 忽略整个目录（含所有内容） | node_modules/ | | *.后缀 | 忽略指定后缀的所有文件 | *.log | | !规则 | 反向取回，取消忽略 | !keep.txt | | | 匹配任意层级目录 | /temp/ |

要注意的细节：目录规则结尾的斜杠表示「这是一个目录，连同内容一起忽略」；! 取反要写在对应忽略规则之后才有效；** 用于跨层匹配，普通 * 不跨目录层级。

新手直接抄的常见模板

下面这些条目覆盖了绝大多数项目的通用需求，可以直接组合使用。系统与编辑器相关的：

Thumbs.db（Windows 缩略图缓存）
.DS_Store（macOS 自动生成）
.vscode/（VS Code 工作区配置，也可选择性保留）
.idea/（JetBrains 系 IDE 配置）

项目与运行相关的：

node_modules/（Node.js 依赖目录）
dist/、build/、target/（构建输出）
.venv/、venv/、__pycache__/（Python 虚拟环境与缓存）
*.log、*.tmp（日志与临时文件）
.env、.env.local（环境变量与密钥，这行最重要，密钥一旦提交进仓库就相当于泄露）

实际项目中，语言和框架会有官方推荐的 .gitignore 模板，GitHub 上也有按语言整理的模板库，从那里复制一份再按需增删，比从零写要可靠。

已经跟踪的文件不生效，这是最大的坑

很多人写了 .gitignore 却发现文件还在仓库里，原因几乎都是同一个：规则只对未被跟踪的文件生效，而这个文件之前已经被 git add 或 commit 过了，Git 会继续跟踪它。

解决办法是解除跟踪，同时保留本地文件：

git rm --cached 文件名
git rm -r --cached 目录名/
git commit -m "停止跟踪不必要的文件"

执行后这个文件就从 Git 的跟踪列表里移除，但还留在你的磁盘上，之后 .gitignore 的规则就生效了。反过来，如果你用 git rm 不带 --cached 删除，本地文件也会一起被删，动手前看清楚。

另一个常见陷阱是 gitignore 规则写对但没生效，比如目录名写错、/ 用错位置、或者规则写在了错误的层级。遇到「明明加了规则却不生效」，按这个顺序查：文件是不是已经被跟踪（用 git status 看）、规则路径是否匹配、规则有没有被后面的 ! 取反。

几个常被问到的细节

用久了还会碰到几个细节问题，一次说清：

子目录里也能放 .gitignore，父目录和子目录的规则叠加生效。项目根目录放通用规则，某个子项目需要特殊处理时，在子目录里再放一份补充即可，不需要把所有规则堆在根目录一份文件里。
忽略不等于删除。被忽略的文件仍然完整保留在磁盘上，只是 Git 不再跟踪、不会被提交，也不会被推到远程仓库，不用担心写进 .gitignore 会丢文件。
一个容易踩的坑：如果整个目录被忽略（比如 node_modules/），这个目录里的文件不能用 ! 规则单独取回。Git 不会去扫描被忽略的目录，取反规则自然失效；想选择性取回一部分，得先取消目录忽略，再对具体文件做细化。
.gitignore 本身是受 Git 管理的文件，修改后正常提交就会进入仓库，其他协作者拉到代码后会自动获得相同规则；它不会自动同步到其他分支，改了记得提交到目标分支。

构建一下：用 VS Code 管理效果更好

在 VS Code 里编辑 .gitignore 有语法高亮和文件图标提示，比记事本直观。VS Code 自带的源代码管理面板会实时显示哪些文件被忽略（显示为灰色），提交前扫一眼面板，能直观看到忽略规则是否按预期工作。装好 Git 之后，用 VS Code 打开项目仓库，左侧活动栏的源代码管理图标就是日常提交入口，被忽略的文件不会出现在待提交列表里。

做完这几件再确认忽略规则生效

[ ] .gitignore 放在仓库根目录，UTF-8 编码
[ ] 已跟踪文件先执行 git rm --cached 或 git rm -r --cached 解除跟踪并提交
[ ] .env 等密钥文件确认已加入忽略并解除跟踪
[ ] 在 VS Code 源代码管理面板确认目标文件显示为灰色（被忽略）
[ ] 提交后用 git status 复查，忽略列表符合预期