本文从 Obsidian 撰写发布

Git 文件排除（.gitignore）完全教程

1. 什么是 .gitignore

.gitignore 是 Git 版本控制系统中的一个配置文件，用于指定哪些文件或目录不应该被 Git 跟踪（即不提交到仓库中）。

为什么要使用 .gitignore？

原因	说明
减小仓库体积	避免将庞大的依赖目录（如 node_modules/）提交到仓库
保护敏感信息	防止将 .env 等包含密码、密钥的文件泄露
避免平台差异	忽略操作系统生成的垃圾文件（如 .DS_Store）
提高协作效率	每个人可以保留自己的 IDE 配置，不强制统一
保持仓库干净	只提交源代码和必要的配置文件

核心原则

Git 忽略规则由 .gitignore 文件控制，而不是由 VS Code 或其他编辑器控制。VS Code 只是编辑工具，真正的忽略行为由 Git 执行。

2. 基本语法规则

2.1 注释

使用 # 开头表示注释，Git 会忽略该行。

这是一条注释

下面的规则会忽略 node_modules 目录

node_modules/

2.2 通配符

符号	含义	示例
*	匹配 0 个或多个字符	*.log 忽略所有 .log 文件
?	匹配 1 个字符	?.txt 忽略 a.txt、b.txt，但不忽略 ab.txt
[abc]	匹配括号中的任意一个字符	[Oo]bj/ 忽略 Obj/ 和 obj/
**	匹配任意层级的目录	**/temp 忽略所有层级的 temp 目录

2.3 路径匹配

写法	含义
node_modules	忽略任何位置的 node_modules 目录或文件
/node_modules	只忽略项目根目录下的 node_modules
node_modules/	忽略名为 node_modules 的目录（与 node_modules 效果相同）
src/*.js	忽略 src/ 目录下的所有 .js 文件
src/*/.js	忽略 src/ 及其所有子目录中的 .js 文件

2.4 取反规则

使用 ! 前缀可以例外某些文件，即使它们被前面的规则匹配了。

忽略所有 .env 文件

*.env

但保留 .env.example

!.env.example

3. 常见忽略规则

3.1 依赖目录

Node.js

node_modules/

Python

venv/
env/
__pycache__/
*.pyc

Java

target/
*.class

PHP

vendor/

Ruby

vendor/bundle/

3.2 编译输出

通用

build/
dist/
out/
bin/
obj/

特定语言

*.o
*.exe
*.dll
*.so
*.dylib

3.3 环境变量与敏感信息

环境变量文件

.env
.env.local
.env.*.local
.env.production
.env.development

密钥文件

*.pem
*.key
*.crt

3.4 日志文件

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

3.5 测试覆盖率

coverage/
.nyc_output/
*.lcov

3.6 操作系统文件

macOS

.DS_Store
.AppleDouble
.LSOverride

Windows

Thumbs.db
desktop.ini

Linux

*~
.directory

3.7 IDE 配置（可选）

VS Code

.vscode/
*.code-workspace

IntelliJ / WebStorm

.idea/
*.iml

Sublime Text

*.sublime-project
*.sublime-workspace

Vim

*.swp
*.swo
*.swn

4. 实战案例：Node.js 项目

4.1 项目结构

my-project/
├── .gitignore
├── package.json
├── package-lock.json
├── .env
├── src/
│ └── index.js
├── node_modules/
├── dist/
└── logs/

└── app.log

4.2 标准 .gitignore 配置

==================================================

Node.js 项目标准 .gitignore

==================================================

依赖

node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*

环境变量

.env
.env.local
.env.*.local
.env.production
.env.development

构建输出

dist/
build/
out/
.vercel/
.netlify/

日志

*.log
logs/
.log.

测试覆盖率

coverage/
.nyc_output/
*.lcov

缓存

.cache/
.parcel-cache/
.eslintcache
*.tsbuildinfo

操作系统文件

.DS_Store
Thumbs.db
desktop.ini

IDE（可选，根据需要开启）

.vscode/

.idea/

*.swp

*.swo

其他

*.tmp
*.temp
*.bak

4.3 验证命令

检查哪些文件会被忽略

git status --ignored

检查某个文件是否被忽略

git check-ignore -v node_modules/package.json

查看 .gitignore 中是否有重复行

grep -v '^#' .gitignore | grep -v '^$' | sort | uniq -d

5. 常见错误与解决方案

5.1 重复规则

问题：同一个规则写了多次

node_modules/ # 第 1 次

npm

node_modules # 第 2 次（重复了！）

解决方案：只保留一条

node_modules/ # 只保留这一条就够了

5.2 规则太宽泛

问题：使用了过于通用的规则，误伤了重要文件

bin/ # 可能误伤项目根目录下的 bin/ 脚本目录

解决方案：

方案 1：只忽略特定路径的 bin/

dist/bin/

方案 2：如果确实不需要 bin/，保留但加注释说明

bin/

5.3 文件已被跟踪，.gitignore 不生效

问题：node_modules/ 已经被提交到仓库了，现在才添加 .gitignore 规则

解决方案：

1. 从 Git 跟踪中移除（保留本地文件）

git rm -r --cached node_modules

2. 提交变更

git commit -m "Remove node_modules from version control"

3. 推送到远程

git push

关键点：--cached 参数表示只删除 Git 索引中的记录，不删除本地实际文件。

5.4 .gitignore 文件本身未被提交

问题：创建了 .gitignore 但忘记提交它

解决方案：

git add .gitignore
git commit -m "Add .gitignore"
git push

5.5 混淆 / 的作用

写法	含义	是否递归
node_modules	忽略任何位置的 node_modules	是
node_modules/	忽略名为 node_modules 的目录	是
/node_modules	只忽略根目录下的 node_modules	否
/node_modules/	只忽略根目录下的 node_modules 目录	否

建议：除非你明确知道需要限制在根目录，否则使用 node_modules/ 即可。

6. 最佳实践

尽早创建 .gitignore
在项目初始化时（git init 之后）就创建 .gitignore，避免无关文件被意外提交。
使用通用模板
访问 gitignore.io 输入项目类型（如 Node,VisualStudioCode,macOS），自动生成完整的 .gitignore。
团队共享
将 .gitignore 提交到仓库，确保所有成员使用相同规则。
定期清理
定期检查 .gitignore 是否包含了过时的规则，保持配置干净。
使用全局 .gitignore
如果有一些文件在所有项目中都需忽略（如 .DS_Store），可以配置全局忽略：

创建全局 .gitignore

echo ".DS_Store" >> ~/.gitignore_global

配置 Git 使用它

git config --global core.excludesfile ~/.gitignore_global

谨慎使用取反规则
! 取反规则容易造成混乱，使用时确保优先级清晰。

7. 完整配置模板

7.1 通用模板（适用于大多数 Web 项目）

==================================================

.gitignore 通用模板

适用于：Node.js / JavaScript / TypeScript 项目

==================================================

依赖

node_modules/
jspm_packages/

日志

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

环境变量

.env
.env.*
!.env.example

构建输出

dist/
build/
out/
lib/
*.tsbuildinfo

测试覆盖率

coverage/
.nyc_output/

缓存

.cache/
.parcel-cache/
.eslintcache
.vite/

IDE 配置

.vscode/
.idea/
*.swp
*.swo
*~
.project
.classpath
.settings/

操作系统文件

.DS_Store
.AppleDouble
.LSOverride
Thumbs.db
desktop.ini
ehthumbs.db

压缩文件

*.7 z
*.rar
*.zip
*.gz
*.tgz

临时文件

*.tmp
*.temp
*.bak
*.swp
*.swo

其他

*.pem
*.key
*.crt
*.p 12
*.pfx

7.2 混合项目模板（ActionScript + Node.js + Eclipse）

==================================================

.gitignore 混合项目模板

适用于：ActionScript + Node.js + Eclipse

==================================================

构建输出 (Flash Builder)

bin-debug/
bin-release/
[Oo]bj/

Node.js 依赖

node_modules/

Eclipse 项目设置

.settings/

注意：保留以下 Eclipse 项目文件

.project

.actionScriptProperties

.flexProperties

编译后二进制文件

*.swf
*.air
*.ipa
*.apk
*.exe
*.dll

环境变量

.env
.env.local
.env.*.local

日志

*.log
npm-debug.log*

测试覆盖率

coverage/
.nyc_output/

操作系统文件

.DS_Store
Thumbs.db

IDE 配置（可选）

.vscode/
.idea/
*.swp
*.swo

8. 快速参考卡

需要忽略的内容	.gitignore 写法
Node.js 依赖	node_modules/
环境变量文件	.env
日志文件	*.log
构建输出目录	dist/
测试覆盖率	coverage/
macOS 垃圾文件	.DS_Store
Windows 垃圾文件	Thumbs.db
所有 .tmp 文件	*.tmp
根目录下的 temp/	/temp/
任何位置的 temp/	temp/
忽略除 .example 外的所有 .env 文件	*.env 和 !.env.example

9. 总结

.gitignore 是 Git 的核心配置文件，与 VS Code 无关
规则要精简，避免重复和无意义的条目
注意 / 的位置：开头表示根目录，末尾表示目录
已跟踪文件不受 .gitignore 影响，需用 git rm --cached 移除
团队协作记得提交 .gitignore 文件
使用在线工具生成模板，省时省力

本文档基于 Git 标准语法编写，适用于所有 Git 版本。

# Git