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