6.4 .gitignore 最佳实践

---

1. 为什么要学这个?

你的队友从GitHub克隆了你的项目,发现下载了足足500MB。他很震惊:"就几个文件,怎么这么大?"

打开一看,里面有一个巨大的node_modules文件夹,还有一堆.log日志,甚至还有你不小心拖进去的截图。

500MB的仓库,队友每次克隆都要骂娘。

---

2. 核心概念

2.1 .gitignore - Git的黑名单

就像机场安检的禁止携带清单。

• 没有清单:什么都能带上飞机,包括打火机、水果刀
• 有了清单:安检会拦住这些危险品,不让它们上飞机

技术定义:.gitignore是一个文本文件,用于指定Git应该忽略哪些未跟踪的文件。被忽略的文件不会出现在git status的未跟踪列表中,也不会被git add .包含。

2.2 哪些文件应该被忽略?

1. 依赖包(node_modules/)

   • 体积巨大(几百MB),且可以通过pnpm install重新安装
   • 就像:你不会把超市的货架搬回家,只需要带购物清单(package.json)

2. 构建产物(.next/, dist/)

   • 这些是代码编译后的结果,可以随时通过pnpm build重新生成
   • 就像:你不会把做好的饭菜打包带走,只需要带菜谱(源代码)

3. 系统生成文件(.DS_Store, Thumbs.db)

   • 这是操作系统自动生成的,与项目代码无关

4. 敏感配置(.env)

   • 包含数据库密码、API密钥,一旦泄露后果严重

---

3. 标准模板

在项目根目录(和package.json同级)新建文件.gitignore,复制以下内容:

# 1. 依赖包
node_modules/
.pnpm-store

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

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

# 4. 系统垃圾
.DS_Store
Thumbs.db
*.log

---

4. 应用场景

文件类型	是否忽略?	理由
src/main.ts	Keep	这是源代码,必须传
package.json	Keep	这是购物清单,队友根据它买依赖
node_modules/	Ignore	这里面有几万个文件,体积巨大,且可以重新生成
.env.local	Ignore	包含私钥
npm-debug.log	Ignore	报错现场记录,没价值

---

5. 救火方案

如果你已经把node_modules传上去了,光改.gitignore文件没用,因为Git已经记住了这些文件。需要从Git的"记忆"里删除:

# 从Git索引中删除,但保留本地文件
git rm -r --cached .

# 重新添加所有文件(这时候gitignore才会生效)
git add .
git commit -m "Fix: apply gitignore"

---

6. 避坑指南

✅ 推荐做法	❌ 禁忌
先写.gitignore再写代码	项目做了一半才想起来加(这时候历史记录已经脏了)
使用通配符(*.log)	一个个列出文件名(累死你)
检查状态(git status)	盲目执行git add .(这就是万恶之源)

---

7. 本章小结

Vibe心法:仓库不是垃圾箱,也不是备份站——排除node_modules和构建产物,确保每次运行都是基于package.json的纯净重构。

关键要点:

1. 📦 减肥:忽略node_modules可以让你的仓库从500MB瘦身到500KB
2. 🔐 安全:忽略.env是防止密钥泄露的第一道防线
3. 🎯 专业:不上传.DS_Store等系统垃圾,体现了你的职业素养
4. 🔄 可重现:依赖包和构建产物都可以重新生成,不需要版本控制