gitignore最佳实践
# .gitignore 最佳实践
# 什么是 .gitignore？
.gitignore 是一个文本文件，告诉 Git 哪些文件或目录不应该被跟踪（不纳入版本控制）。
应该忽略的文件类型：
- 构建产物：
dist/、target/、build/、*.class - 依赖目录：
node_modules/、.mvn/ - IDE 配置：
.idea/、.vscode/、*.iml - 环境变量文件：
.env.local、.env.*.local（含敏感信息） - 系统文件：
.DS_Store、Thumbs.db - 日志文件：
*.log、logs/ - 缓存目录：
.vite/、.cache/
不应该忽略的文件：
- 源代码
- 配置文件模板（如
.env.example、.env.development） - 文档（README、DESIGN 等）
- 依赖锁定文件（
pnpm-lock.yaml、package-lock.json、pom.xml）
# .gitignore 语法规则
| 语法 | 含义 | 示例 |
|---|---|---|
# | 注释 | # 这是注释 |
*.log | 匹配所有 .log 文件 | error.log、app.log |
node_modules/ | 匹配名为 node_modules 的目录（任意层级） | src/node_modules/、node_modules/ |
/dist | 只匹配根目录下的 dist | dist/（不匹配 src/dist/） |
dist/ | 匹配任意层级的 dist 目录 | dist/、src/dist/ |
!file | 取反，强制跟踪（即使前面被忽略） | !lib/import.js |
**/logs | 匹配任意层级的 logs 目录 | logs/、a/b/logs/ |
temp/*.txt | 匹配 temp 目录下的 .txt 文件 | temp/test.txt |
注意：
!取反规则不能重新包含已经被上级目录忽略的文件。例如node_modules/已忽略，!node_modules/lib.js无效。
# 各技术栈 .gitignore 模板
# Java / Spring Boot
# 构建产物
target/
*.class
*.jar
*.war
# Maven
.mvn/
mvnw
mvnw.cmd
# IDE
.idea/
*.iml
*.iws
*.ipr
.vscode/
.settings/
.project
.classpath
# 日志
*.log
logs/
# 系统
.DS_Store
Thumbs.db
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# Node.js / Vue / 前端
# 依赖
node_modules/
# 构建产物
dist/
dist-ssr/
# 缓存
.vite/
.cache/
*.tsbuildinfo
# 环境变量（含敏感信息）
.env.local
.env.*.local
# 日志
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
# IDE
.idea/
.vscode/
*.suo
*.ntvs*
*.njsproj
*.sln
# 系统
.DS_Store
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# uniapp / 小程序
# 依赖
node_modules/
# 构建产物
dist/
unpackage/
# 环境变量
.env.local
.env.*.local
# 缓存
.vite/
*.tsbuildinfo
# pnpm
.pnpm-store/
# 微信开发者工具（含本地配置，不应提交）
project.private.config.json
# IDE
.idea/
.vscode/
.DS_Store
*.log
*.local
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# 通用根仓库（管理多子项目）
# IDE
.idea/
.vscode/
# 系统
.DS_Store
Thumbs.db
# 日志
*.log
1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
子项目各自有自己的
.gitignore，根仓库只需忽略 IDE 和系统文件。
# 常见问题与陷阱
# 1. .gitignore 不生效？
原因：文件已经被 Git 跟踪了，.gitignore 只对未跟踪的文件生效。
解决：先从 Git 索引中移除（不删除本地文件），再提交：
# 移除单个文件
git rm --cached <file>
# 移除整个目录
git rm -r --cached <directory>
# 提交
git commit -m "chore: 移除不应跟踪的文件，添加 .gitignore"
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
--cached参数表示只从 Git 索引中移除，不删除本地文件。
# 2. 已经提交了 .env 等敏感文件怎么办？
# 1. 从历史记录中彻底移除（谨慎操作）
git filter-branch --force --index-filter \
'git rm --cached --ignore-unmatch .env' \
--prune-empty --tag-name-filter cat -- --all
# 2. 添加到 .gitignore
echo ".env" >> .gitignore
# 3. 强制推送
git push --force --all
# 4. ⚠️ 立即更换所有泄露的密钥/密码！
1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
即使从 Git 历史中移除，如果已经推送到公开仓库，敏感信息可能已被他人获取。务必更换密钥。
# 3. 全局 .gitignore
可以为所有项目设置一个全局 .gitignore，忽略系统文件和 IDE 文件：
# 创建全局 .gitignore 文件
echo ".DS_Store
.idea/
.vscode/
*.iml
Thumbs.db" > ~/.gitignore_global
# 配置 Git 使用全局 .gitignore
git config --global core.excludesfile ~/.gitignore_global
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
项目级
.gitignore和全局.gitignore会同时生效，取并集。
# 4. 查看某个文件为什么被忽略
git check-ignore -v <文件路径>
# 示例输出：
# .gitignore:3:node_modules/ node_modules/express
# 表示 .gitignore 第 3 行的 node_modules/ 规则忽略了这个文件
1
2
3
4
5
2
3
4
5
# .gitignore 编写建议
- 早建早好：项目初始化时就创建
.gitignore，避免后续清理麻烦 - 宁多勿少：不确定是否该跟踪的文件，先忽略。需要跟踪时用
!取反 - 按技术栈选择：参考 github/gitignore (opens new window) 官方模板
- 团队统一：
.gitignore提交到仓库，团队成员共享同一份配置 - 不要忽略锁定文件：
pnpm-lock.yaml、package-lock.json、pom.xml等依赖锁定文件必须提交，保证团队依赖版本一致
# 学习参考
上次更新: 2026/7/24 16:59:26