.gitignore 速查表 - 忽略规则与写法大全
误把 node_modules 或 .env 提交进仓库，是几乎所有项目都会踩一次的坑。这份 .gitignore 参考按 5 组整理基础匹配语法、通配与注释、目录与文件、全局忽略与生效命令，以及常见语言模板。不确定某条规则是否命中时，用 git check-ignore -v 验证；已追踪的文件要先 git rm --cached 才停止追踪。读完后你能写出既安全又不会漏文件的忽略规则。
基本语法 Syntax 6
*.logbuild//dist**/node_modulesdoc/*.txt!keep.txt通配与注释 Patterns 6
?[abc]**# note\#file\!imp目录与文件 Dirs & Files 4
.cache*.tmplogs/*.log*.swp全局与生效 Global 4
git config --global core.excludesfile ~/.gitignore_globalgit check-ignore -v filegit rm --cached filegit add -f file常见语言模板 FAQ 4
node_modules/.env__pycache__/.DS_Store命令示例
确认某个文件究竟被哪条规则忽略
git check-ignore -v .env输出两列分别是命中的规则文件与规则内容，排「我明明加了忽略规则却不生效」的问题时最直接。没有任何输出说明文件未被忽略。
输出
.gitignore:18:.env .env
文件已被追踪，加进 .gitignore 不生效
git rm --cached .env
git commit -m "stop tracking .env".gitignore 只影响未追踪的文件。已入库的文件必须先 git rm --cached 移出索引，本地文件与提交历史都保留。密钥文件还需轮换，已泄露的密钥改 ignore 无效。
输出
rm '.env'
只在根目录忽略 dist，子目录里的同名目录保留
/dist开头的斜杠锚定到仓库根；而 dist/ 或 **/dist 会匹配任意层级。路径锚定这个区别在 monorepo 里很关键，否则会误伤子包。
常见坑与注意事项
- 把 .env 写进 .gitignore 不能撤回已提交过的密钥，泄露后必须轮换密钥，改 ignore 只防未来。
- 已追踪的文件加 ignore 规则无效，须 git rm --cached 移出索引。
- 忽略规则用 / 锚定根目录时，只对根目录生效；去掉斜杠会匹配所有层级，可能误伤 monorepo 子包。
- 不要用 ignore 代替提交：强制 git add -f 会把本该排除的构建产物和密钥重新拉回版本库。
- 否定规则 !keep.txt 必须排在被它覆盖的规则之后，顺序反了不会生效。
提示
- 模式匹配相对 .gitignore 所在目录，根目录用 /dist 锚定。
- 先写否定规则 !file 时，其父目录必须未被忽略。
- git check-ignore -v file 可查出哪条规则忽略了某文件。
- 已追踪的文件需 git rm --cached 后才停止追踪。
常见问题
怎么写 .gitignore？
在项目根目录建 .gitignore，每行写一条匹配规则：目录加尾斜杠（build/），文件直接写名（.env），通配用 *（*.log），否定规则用 ! 恢复被忽略的项。常见依赖与密钥模式（node_modules/、.env）直接加进去就能避免误提交。
怎么在 Git 里忽略 node_modules 和 .env？
在 .gitignore 加两行：node_modules/ 与 .env（含 .env.local 等变体可用 .env* 配合 !.env.example）。已跟踪的文件要先 git rm --cached 再忽略才会生效。
.gitignore 和全局忽略有什么区别？
项目 .gitignore 只对该仓库生效；全局忽略（git config --global core.excludesfile ~/.gitignore_global）对所有仓库生效，适合放编辑器缓存、OS 隐藏文件等通用项。两者语法一致。
怎么检查某条忽略规则是否命中了文件？
用 git check-ignore -v <文件> 查看是哪一行规则命中以及来源文件；无输出说明未被忽略。排错时先确认路径写法与否定规则的先后顺序。
gitignore 的感叹号和斜杠是什么意思？
行尾 / 表示只匹配目录；! 开头是否定规则，把前面被忽略的项重新纳入跟踪（否定规则要写在更宽泛的忽略之后才生效）；/ 开头表示只匹配仓库根目录下的路径。
由 巧匠 维护
公开更新于 2026年8月2日，内容持续校对官方文档。