.gitignore 模板与常用忽略规则大全

一个精心编写的 .gitignore 文件可以通过排除构建产物、依赖项、密钥和操作系统特定文件来保持仓库整洁。本指南全面介绍了 gitignore 语法、各主流语言和框架的模板、IDE 配置、常见错误以及我们的生成器工具。

什么是 .gitignore — 语法规则

.gitignore 文件告诉 Git 哪些文件和目录应该排除在版本控制之外。它使用简单的模式匹配语法：

• # — 注释 — 以 # 开头的行是注释，Git 会忽略它们。
• ! — 否定 — 在模式前加 ! 可以重新包含之前被排除的文件。
• / — 目录 — 在模式末尾添加 / 仅匹配目录，不匹配同名文件。
• * ** ? — 通配符 — 使用 * 匹配任意字符（/ 除外），** 匹配嵌套目录，? 匹配单个字符。
• 锚定 — 不含 / 的模式在整个目录树中匹配。前导 / 锚定到仓库根目录。

语法示例

# Ignore all .log files
*.log

# Ignore the build directory
build/

# Ignore all files in temp/ recursively
temp/**

# But keep .gitkeep files
!temp/.gitkeep

# Ignore .env in root only
/.env

# Ignore all .txt files in doc/ and subdirectories
doc/**/*.txt

# Ignore any file named "secret" anywhere
secret

全局与本地 .gitignore

Git 支持三个级别的忽略规则，每个级别有不同的用途：

设置全局 gitignore：

# Create a global gitignore file
touch ~/.gitignore_global

# Tell Git to use it
git config --global core.excludesfile ~/.gitignore_global

# Add common patterns
echo ".DS_Store" >> ~/.gitignore_global
echo "Thumbs.db" >> ~/.gitignore_global
echo ".idea/" >> ~/.gitignore_global
echo ".vscode/" >> ~/.gitignore_global
echo "*.swp" >> ~/.gitignore_global

Node.js .gitignore 模板

Node.js 项目的基本 .gitignore。涵盖 npm/yarn/pnpm 依赖文件夹、构建输出、环境文件和缓存：

# Dependencies
node_modules/
.pnp
.pnp.js

# Build output
dist/
build/
out/

# Environment files
.env
.env.local
.env.*.local

# Testing
coverage/

# Cache
.cache/
.parcel-cache/
.next/
.nuxt/
.turbo/

# Debug logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*

# Editor directories and files
*.tsbuildinfo

• node_modules/ — npm/yarn/pnpm 安装的依赖项。始终从 package.json 重新生成。
• dist/ 和 build/ — 编译输出。由构建工具重新生成。
• .env 文件 — 包含 API 密钥、数据库密码和其他密钥。绝不要提交这些文件。
• coverage/ — Jest、Istanbul 或 c8 生成的测试覆盖率报告。
• .cache/ — Babel、Parcel、Webpack 等的构建缓存。
• 调试日志 — npm-debug.log、yarn-debug.log、yarn-error.log 文件。

Python .gitignore 模板

Python 项目会生成许多字节码和构建产物。此模板涵盖所有常见模式：

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

# Virtual environments
venv/
.venv/
env/
ENV/

# Distribution / packaging
dist/
build/
*.egg-info/
*.egg
.eggs/
*.whl

# Testing
.pytest_cache/
.coverage
htmlcov/
.tox/
.nox/

# Type checking
.mypy_cache/
.pytype/
.pyre/

# IDE
.spyderproject
.spyproject

# Jupyter
.ipynb_checkpoints/

# Environment
.env
.env.local

• __pycache__/ 和 *.pyc — Python 字节码文件。导入时自动重新生成。
• venv/ 和 .venv/ — 虚拟环境目录。每个开发者创建自己的。
• *.egg-info/ 和 dist/ — setuptools/pip 的包分发产物。
• .mypy_cache/ — mypy 的类型检查缓存。
• .pytest_cache/ — Pytest 会话缓存。
• .tox/ — Tox 测试环境目录。

Java / Kotlin .gitignore 模板

使用 Maven 或 Gradle 的 Java 和 Kotlin 项目会生成编译的类文件和构建目录：

# Compiled class files
*.class

# Maven
target/
pom.xml.tag
pom.xml.releaseBackup
pom.xml.versionsBackup
pom.xml.next
release.properties

# Gradle
build/
.gradle/
gradle-app.setting
!gradle-wrapper.jar
!gradle-wrapper.properties

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

# IDE - IntelliJ
.idea/
*.iws
*.iml
*.ipr
out/

# IDE - Eclipse
.classpath
.project
.settings/
bin/

• *.class — 编译的 Java 字节码文件。
• target/ — Maven 构建输出目录。
• build/ — Gradle 构建输出目录。
• .gradle/ — Gradle 包装器缓存和配置。
• *.jar、*.war、*.ear — 编译的归档文件。应使用依赖管理代替。
• .idea/ — IntelliJ IDEA 项目文件（也在 IDE 部分介绍）。

React / Next.js .gitignore 模板

React 和 Next.js 项目结合了 Node.js 模式和框架特定目录：

# Dependencies
node_modules/

# Next.js
.next/
out/

# Production build
build/
dist/

# Environment files
.env
.env.local
.env.development.local
.env.test.local
.env.production.local

# Testing
coverage/

# Vercel
.vercel/

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

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

# Cache
.cache/
.turbo/

• .next/ — Next.js 构建输出和缓存。每次构建时重新生成。
• out/ — Next.js 静态导出输出目录。
• node_modules/ — 与任何 Node.js 项目相同。
• .env.local 和 .env*.local — 包含密钥的本地环境覆盖。
• .vercel/ — Vercel CLI 部署配置。

Go .gitignore 模板

Go 项目通常很精简，但仍有一些文件需要排除：

# Binaries
bin/
*.exe
*.exe~
*.dll
*.so
*.dylib

# Test binary
*.test

# Output of go coverage
*.out

# Vendor (optional — some teams commit vendor/)
vendor/

# Go workspace
go.work

# IDE
.idea/
.vscode/

# OS
.DS_Store
Thumbs.db

# Environment
.env

• bin/ — 编译的二进制输出目录。
• vendor/ — 第三方依赖（如果未使用 Go modules 或你选择排除的话）。
• *.exe、*.exe~、*.dll、*.so、*.dylib — 各平台的编译二进制文件。
• *.test — go test -c 生成的编译测试二进制文件。
• *.out — go test -coverprofile 生成的覆盖率输出文件。

Rust .gitignore 模板

Rust 和 Cargo 项目的忽略设置很简单：

# Build artifacts
/target/

# Cargo.lock — ONLY ignore for libraries
# For binaries (applications), DO commit Cargo.lock
# Cargo.lock

# Debug symbols (Windows)
*.pdb

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

# OS
.DS_Store
Thumbs.db

# Environment
.env

• target/ — 所有构建产物，包括调试和发布版本、增量编译缓存。
• Cargo.lock — 对于库项目，Cargo.lock 不应该提交（消费者会重新生成）。对于二进制/应用项目，应该提交 Cargo.lock。
• *.pdb — Windows 调试符号文件。

IDE 与操作系统模式

这些模式理想情况下应该放在全局 ~/.gitignore_global 中，以保持仓库 .gitignore 的整洁。但如果团队一致同意，也可以添加到项目 .gitignore 中：

# ─── VS Code ───
.vscode/
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/extensions.json

# ─── JetBrains IDEs ───
.idea/
*.iws
*.iml
*.ipr

# ─── Vim ───
*.swp
*.swo
*~
.netrwhist

# ─── Sublime Text ───
*.sublime-workspace
*.sublime-project

# ─── macOS ───
.DS_Store
.AppleDouble
.LSOverride
._*

# ─── Windows ───
Thumbs.db
Thumbs.db:encryptable
ehthumbs.db
Desktop.ini

# ─── Linux ───
*~
.fuse_hidden*
.Trash-*

• .vscode/ — VS Code 工作区设置。也可以提交 .vscode/settings.json 但忽略 .vscode/launch.json。
• .idea/ — JetBrains IDE（IntelliJ、WebStorm、PyCharm）项目目录。
• .DS_Store — macOS Finder 元数据文件。在 Finder 中打开的每个目录都会创建。
• Thumbs.db — Windows 缩略图缓存文件。
• *.swp、*.swo — Vim 编辑时创建的交换文件。
• *.sublime-workspace — Sublime Text 工作区文件。

常见错误与修复

即使是经验丰富的开发者也会犯这些 .gitignore 错误。以下是诊断和修复每个错误的方法：

# Remove file from Git tracking (keeps it on disk)
git rm --cached .env

# Remove an entire directory from tracking
git rm -r --cached node_modules/

# Commit the change
git add .gitignore
git commit -m "Stop tracking ignored files"

# Verify it worked
git status

# WRONG — negation before exclusion has no effect
!important.log
*.log

# CORRECT — exclude first, then negate
*.log
!important.log

# Another example: ignore everything in docs/ except PDFs
docs/*
!docs/*.pdf

# 1. Add .env to .gitignore
echo ".env" >> .gitignore

# 2. Remove from Git tracking
git rm --cached .env

# 3. Commit
git add .gitignore
git commit -m "Remove .env from tracking"

# 4. IMPORTANT: Rotate all secrets in that .env file!
# The old values are still in Git history.

# Matches both a FILE named "logs" and a DIRECTORY named "logs"
logs

# Matches ONLY a directory named "logs"
logs/

# Example: you have a file "build" and a directory "build/"
# "build" in .gitignore ignores BOTH
# "build/" in .gitignore ignores only the directory

.gitignore 生成器与工具

与其手动编写 .gitignore 文件，不如使用生成器工具为你的项目技术栈创建全面的模板：

• 我们的 Gitignore 生成器工具让你选择语言、框架和 IDE，几秒钟内创建完整的 .gitignore 文件。
• GitHub 在 github/gitignore 仓库中维护了大多数语言和框架的 .gitignore 模板集合。
• 专业提示：从生成的模板开始，然后根据你的特定项目需求进行自定义。随着项目的发展，定期检查。

常见问题