给 trae-novel 配 .gitignore 差点踩坑：别一上来就忽略整个目录

上周我在维护 trae-novel 这个小说数据采集项目时，遇到了一件差点闯大祸的事：我给 .gitignore 追加了一堆规则后，差点把攒了两周的番茄小说榜单原始数据、还有整理好的全量小说目录 txt 全给弄丢。后来复盘整个配置过程，发现很多人在配 .gitignore 时都会犯「上来就加宽泛规则」的错，今天就把这次的经验和踩坑点整理出来。

配 .gitignore 前，先做三步排查，别上来就写规则

当时接到「追加 .gitignore 条目并检查合理性」的任务后，我没有直接照搬网上的通用模板，而是先做了三步前置排查：
第一步先拉项目当前状态，确认现有 .gitignore 只追加了少量条目，没有大范围改动；第二步核对新增规则和项目产物的匹配度，先搞清楚项目里到底有什么需要忽略的文件；第三步再判断规则是否合理。
排查过程中我发现 trae-novel 的核心目录结构里，novel/bestsellers/ 存的是每次爬取的番茄小说榜单原始 JSON，还有单独整理的小说目录 txt，这些都是核心业务数据，绝对不能随便加入忽略规则。而需要忽略的只有运行产生的临时文件：比如 Python 缓存 __pycache__、本地虚拟环境 .venv、还有运行时生成的临时缓存文件。

激进配置的代价：差点把已跟踪数据全删掉

初步排查后，当时给出的初步结论是「追加的大方向合理，但最后两个条目偏激进，还踩了一个最常见的 .gitignore 坑」：
很多人不知道，.gitignore 只对未跟踪的文件生效——已经加入版本库的文件，哪怕你在 .gitignore 里加了对应规则，也不会被忽略。当时差点建议加的规则是直接忽略整个 novel/ 目录，但这个目录里已经 tracking 了榜单数据和小说目录，要是真加了这条规则，下次提交时这些核心数据就会被当成未跟踪文件忽略，甚至如果执行 git clean 清理未跟踪文件，两周的工作量直接没了。
除了这个坑，当时还发现目录里存在 20260619 批次的旧榜单数据，这些数据已经不再用于当前功能，但因为没有提前做只读分析，差点直接当成冗余文件删掉。

最终落地的保守版配置：只忽略产物，保留核心数据

最后我改成了保守版配置，核心原则是「只忽略明确的运行产物，不扩大忽略范围」：不再忽略整个 novel/ 树，只忽略明确的本地产物目录，比如 __pycache__/、.venv/、还有本地生成的小说缓存目录，而 novel/bestsellers/ 下的榜单数据、小说目录 txt 这些核心数据全部保留。
改动完成后我做了两步验证：第一步执行 git status 确认新增的忽略规则生效，要忽略的临时文件确实变成了未跟踪状态；第二步列出 novel/bestsellers/ 下的已跟踪文件，确认核心数据没有受影响。
后来处理旧数据清理需求时，我先做了只读分析：看了目录里的文件命名规律是按 YYYYMMDD 标记批次，确认 20260619 的旧批数据确实不再用于当前功能，才执行了安全清理，没有直接删库跑。

可带走的 .gitignore 配置原则

这次踩坑后我总结了 4 个通用的 .gitignore 配置原则，避免大家犯同样的错：

1. 先排查再动手：配规则前先跑 git ls-files 看已跟踪文件，再跑 ls 摸清楚项目结构，区分清楚「核心数据/源码」和「运行产物」，只忽略后者。
2. 粒度从细到粗：先加明确的产物路径（比如 __pycache__/、.venv/），不要一上来就加 /novel、*.log 这种宽泛规则，尤其是目录里有已跟踪内容时，绝对不要先加忽略整个目录的规则。
3. 已跟踪文件要忽略得先移出版本库：如果已经跟踪的文件需要被忽略，先执行 git rm --cached <文件路径> 把文件从版本库移除但保留本地，再加 .gitignore 规则。
4. 改完必须验证：加完规则后跑 git status 确认：要忽略的文件显示为 Untracked，要保留的文件还在跟踪列表里，再提交规则。