.gitignore - 忽略不需要跟踪的文件

简介

并不是所有文件都需要提交到 Git 仓库。有些文件应该被忽略：

• 🔑 密钥和密码文件
• 📦 依赖包（node_modules/）
• 🏗️ 构建产物（dist/、build/）
• 💻 IDE 配置（.vscode/、.idea/）
• 🗑️ 临时文件（.log、.tmp）

.gitignore 文件就是用来告诉 Git 哪些文件应该被忽略。

创建 .gitignore

在项目根目录创建文件：

touch .gitignore

或直接编辑：

code .gitignore

基本语法

1. 忽略单个文件

secret.key
config.local.js

2. 忽略目录

node_modules/
dist/
.cache/

末尾的 / 表示目录。

3. 使用通配符

# 所有 .log 文件
*.log

# 所有 .tmp 文件
*.tmp

# 所有 .env 开头的文件
.env*

4. 否定规则

# 忽略所有 .txt 文件
*.txt

# 但不忽略 important.txt
!important.txt

! 表示例外。

5. 匹配任意目录

# 任意目录下的 .DS_Store
**/.DS_Store

# 等同于
*/.DS_Store

6. 指定目录下的文件

# 只忽略根目录的 TODO
/TODO

# 忽略 build 目录下的所有内容
build/

# 忽略 doc 目录下的 .txt
doc/*.txt

# 忽略 doc 目录及子目录下的 .pdf
doc/**/*.pdf

7. 注释

# 这是注释
# 依赖目录
node_modules/

常见模板

Node.js 项目

# 依赖
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# 环境变量
.env
.env.local
.env.*.local

# 构建产物
dist/
build/
.next/
out/

# 缓存
.cache/
.nuxt/
.vuepress/dist

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# 操作系统
.DS_Store
Thumbs.db

# 测试覆盖率
coverage/
.nyc_output/

# 日志
*.log
logs/

Python 项目

# Byte-compiled / optimized
__pycache__/
*.py[cod]
*$py.class

# C extensions
*.so

# Distribution / packaging
.Python
build/
develop-eggs/
dist/
eggs/
lib/
lib64/
parts/
sdist/
var/
*.egg-info/
.installed.cfg
*.egg

# Virtual environment
venv/
ENV/
env/
.venv

# PyCharm
.idea/

# Jupyter Notebook
.ipynb_checkpoints

# Environment
.env

Java 项目

# Compiled class file
*.class

# Package Files
*.jar
*.war
*.nar
*.ear
*.zip
*.tar.gz
*.rar

# Maven
target/
pom.xml.tag
pom.xml.releaseBackup
pom.xml.versionsBackup

# Gradle
.gradle/
build/

# IntelliJ IDEA
.idea/
*.iws
*.iml
*.ipr

# Eclipse
.classpath
.project
.settings/

React/Next.js 项目

# dependencies
/node_modules
/.pnp
.pnp.js

# testing
/coverage

# next.js
/.next/
/out/

# production
/build

# misc
.DS_Store
*.pem

# debug
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# local env files
.env*.local

# vercel
.vercel

# typescript
*.tsbuildinfo
next-env.d.ts

实战操作

场景 1: 项目开始就创建

# 创建项目
mkdir my-project
cd my-project
git init

# 创建 .gitignore
cat > .gitignore << EOF
node_modules/
.env
dist/
*.log
EOF

# 提交
git add .gitignore
git commit -m "添加 .gitignore"

场景 2: 已经提交了不该提交的文件

# 从 Git 中删除，但保留本地文件
git rm --cached node_modules/ -r
git rm --cached .env

# 添加到 .gitignore
echo "node_modules/" >> .gitignore
echo ".env" >> .gitignore

# 提交
git add .gitignore
git commit -m "添加 .gitignore 并删除不需要的文件"

--cached 表示只从 Git 中删除，不删除本地文件。

场景 3: 忽略已跟踪的文件

# 停止跟踪但保留文件
git rm --cached file.txt

# 添加到 .gitignore
echo "file.txt" >> .gitignore

全局 .gitignore

某些文件在所有项目中都应该忽略（如 .DS_Store）。

创建全局忽略文件

# 创建全局 .gitignore
cat > ~/.gitignore_global << EOF
# 操作系统
.DS_Store
Thumbs.db

# IDE
.vscode/
.idea/
*.swp

# 临时文件
*~
*.tmp
EOF

# 配置 Git
git config --global core.excludesfile ~/.gitignore_global

现在所有项目都会忽略这些文件。

忽略规则优先级

1. 命令行指定的忽略规则
2. 当前目录的 .gitignore
3. 上级目录的 .gitignore
4. .git/info/exclude
5. 全局 .gitignore_global

就近原则：越靠近文件的规则优先级越高。

检查忽略规则

查看文件为什么被忽略

git check-ignore -v node_modules/package.json

输出：

.gitignore:1:node_modules/    node_modules/package.json

表示因为 .gitignore 第 1 行的规则被忽略。

测试文件是否会被忽略

git check-ignore test.log

如果被忽略，会输出文件名。

模式匹配规则

模式	说明	示例
*	匹配任意字符（除 /）	*.log 匹配所有 .log 文件
**	匹配任意目录	**/logs 匹配所有 logs 目录
?	匹配单个字符	file?.txt 匹配 file1.txt
[abc]	匹配方括号中任一字符	file[123].txt
[0-9]	匹配数字范围	log[0-9].txt
/	目录分隔符	/build 只匹配根目录
!	否定（例外）	!important.log

实用技巧

1. 分类组织

# ====================
# 依赖
# ====================
node_modules/
vendor/

# ====================
# 构建产物
# ====================
dist/
build/
*.min.js

# ====================
# 环境配置
# ====================
.env*
!.env.example

# ====================
# IDE
# ====================
.vscode/
.idea/

2. 保留目录结构

# 忽略目录内容但保留目录
logs/*
!logs/.gitkeep

创建空的 .gitkeep 文件保留目录。

3. 临时允许某个文件

# 忽略所有 .env 文件
.env*

# 但保留 .env.example 作为模板
!.env.example

4. 环境特定的忽略

# 开发环境
.env.development

# 生产环境
.env.production

# 但提交模板
!.env.example

在线生成器

gitignore.io

访问 gitignore.io 生成定制的 .gitignore：

# 使用 API 生成
curl -L https://www.toptal.com/developers/gitignore/api/node,python,react > .gitignore

GitHub 模板

GitHub 提供了各种语言的模板： github.com/github/gitignore

常见问题

Q1: 为什么添加了 .gitignore 但文件还在？

原因: 文件已经被跟踪了。

解决:

git rm --cached 文件名
git commit -m "停止跟踪文件"

Q2: 如何忽略文件夹但不忽略某个子文件夹？

# 忽略整个目录
build/

# 但不忽略 build/assets/
!build/assets/

Q3: .gitignore 本身要提交吗？

是的！ .gitignore 应该提交到仓库，这样团队成员都会使用相同的忽略规则。

Q4: 能忽略所有文件除了某几个吗？

# 忽略所有
*

# 但不忽略
!.gitignore
!README.md
!src/

最佳实践

1. 项目开始就创建: 不要等到文件乱了才创建
2. 参考模板: 使用成熟的模板（gitignore.io）
3. 提交 .gitignore: 确保团队使用一致的规则
4. 定期审查: 随着项目发展更新规则
5. 全局 + 本地: 结合使用全局和项目特定的忽略
6. 添加注释: 说明为什么忽略某些文件

安全注意事项

⚠️ 永远不要提交：

• 密钥文件（*.key, *.pem）
• 密码和token
• 环境变量文件（.env）
• 数据库文件（*.sqlite, *.db）
• 个人信息
• API 密钥

如果不小心提交了敏感信息：

1. 立即更改密钥/密码
2. 从历史中删除（使用 git filter-branch 或 BFG Repo-Cleaner）
3. 强制推送

小结

• .gitignore 用于忽略不需要版本控制的文件
• 支持通配符和否定规则
• 项目开始就应该创建
• 使用成熟的模板节省时间
• 已跟踪的文件需要先 git rm --cached
• 敏感信息永远不要提交

下一步

• 远程仓库基础
• 团队协作最佳实践
• Git安全指南

保持仓库整洁，专注于代码本身！✨