给爬虫项目配.gitignore，我差点把核心数据源给忽略没了

上周我接手番茄小说榜单爬虫项目 trae-novel 时，碰上一件怪事：本地跑得好好的爬虫，刚拉完代码的新同事一跑就报错，说找不到榜单数据源。我查了一圈才弄明白，是之前有人往 .gitignore 追加规则时没做校验，直接把整个数据目录给忽略了。.gitignore 看着简单，稍不留神就是大坑。

问题出在「该共享的」没被共享

trae-novel 专门爬番茄小说榜单，核心逻辑是把抓回来的原始 JSON、整理好的小说目录 txt 都存在 novel/ 目录下，供后面分析用。之前有同事嫌仓库文件多，往 .gitignore 里加了条 novel/，本意是忽略本地运行时生成的临时文件，结果这条规则把整个 novel 目录树全忽略了：新 clone 仓库的人本地根本没有榜单数据和配置文件，爬虫直接起不来；

而早就跟踪过这些文件的老开发，本地新增的榜单数据也不会被 git 跟踪，团队数据对不上。我重新梳理才发现，追加规则的「大方向」其实没错——本地产物确实该忽略，但最后两个条目太激进，一刀切忽略了整个数据目录，完全没考虑数据源是要共享的。

核心原则：只忽略本地产物，不碰共享源码和数据源

调整的核心原则就一句：只忽略明确的本地产物，不碰需要共享的源码和数据源。我按这个逻辑走了三步：先看现有改动，当前 .gitignore 只追加了少量条目，最后两条 novel/ 和 novel/bestsellers/ 属于「忽略整个目录」的激进规则；

再看实际文件结构，novel/ 下其实只有两类东西，一类是 bestsellers/ 里按批次命名的番茄榜单原始抓取 JSON，是爬虫核心数据源、得团队共享，另一类是运行时生成的缓存文件和历史旧批次数据，属于本地产物、可以忽略；最后落地的保守版配置只忽略明确的产物，不扩大范围：

最小版规则

# 忽略本地运行产物
novel/cache/
*.log
*.pyc

# 忽略历史旧批次数据（按日期/批次命名，无需共享）
novel/bestsellers/old_batch_*.json

# 忽略个人本地配置文件
config/local.yaml

激进版：忽略整个数据目录 + 白名单

如果是个人用的项目，也可以走「激进但带白名单」的路线，只忽略不需要共享的数据，同时用白名单把核心数据源留出来：

# 激进版：忽略整个数据目录，仅白名单共享必要文件
novel/
!novel/bestsellers/current/  # 白名单：当前有效榜单数据
!novel/config/common.yaml   # 白名单：通用配置

三个容易踩的暗坑

这里有三个容易踩的暗坑。忽略父目录会连带忽略所有子内容——不少人以为加了子目录白名单就能保住文件，但父目录一旦被忽略，子目录所有内容默认都不跟踪，白名单得逐级加，特别容易漏，不如直接忽略具体产物目录踏实。

.gitignore 只对未跟踪文件生效：要是之前已经把 novel/ 下的文件加进了 git 跟踪，后来再加 novel/ 的忽略规则，这些已跟踪文件不会自动从仓库消失，只会忽略本地新增的文件，容易导致仓库和本地不一致。还有别把数据源和运行产物混为一谈——很多人觉得「非代码文件都该忽略」，但爬虫的原始数据、通用配置只要团队要共享，就不能进忽略规则，只有本地生成的缓存、临时文件、个人专属配置才该被忽略。

顺手清掉历史旧批次数据

顺手我还清了批历史旧数据：novel/bestsellers/ 里不少 2024 年 6 月的旧批次榜单 JSON 已经没用了，我先做了只读分析、确认没被当前代码引用，才执行删除，没动当前有效的榜单数据和代码逻辑，避免误删把功能搞挂。

复盘：先理清「该共享的」和「本地产物」

回头看，这趟踩坑的本质是对「该共享的」和「本地产物」边界判断失误。加忽略规则前先理一遍目录结构，分清哪些是团队要共享的源码/数据源、哪些是本地产物；尽量别用「忽略整个目录」的激进规则，优先忽略具体的产物文件或子目录；改完一定跑 git status 验证——要忽略的文件没出现在未跟踪列表里、要共享的文件没被误忽略才算数。如果已有跟踪的文件要加进忽略，得先 git rm --cached <文件路径> 取消跟踪，规则才会真正生效。

---

做自动化这几年，最耗时间的从来不是写代码，是摸清每个平台的脾气。

这篇里提到的坑，都是真金白银踩出来的。
如果你手上也有重复度很高的活儿——批量发布、数据搬运、有固定规则的机械操作
——可以在评论区说说你的场景，我看看能不能自动化掉。