1. 为什么 Git 看不见空文件夹先搞懂 Git 的文件追踪机制在 VSCode 里用 Git 提交代码你一定遇到过这种场景新建了一个文件夹准备放上传文件、日志或者临时生成的资源文件夹明明在资源管理器里躺着切到源代码管理面板一看Git 里居然一个变化都没有。为什么 Git 对空文件夹视而不见这个现象在开发里太常见了我刚带新人的时候几乎每次都会被问到同样的问题。先说结论Git 不是“不让你提交空文件夹”而是它的存储模型里压根没有“空文件夹”这个概念。我在很多项目里帮人排查过类似问题大家第一反应往往是“VSCode 坏了”“Git 没配好”实际上跟编辑器、电脑系统都没关系纯粹是 Git 的设计如此。搞清楚这件事的原理以后遇到任何“文件夹提交不进去”的情况都能秒懂问题出在哪。1.1 Git 到底存了什么从对象模型说起Git 把仓库里的所有东西抽象成三种核心对象blob、tree、commit。你可以把它们理解成三种不同作用的笔记本blob 记录的是文件内容相当于某一个时刻文件内容的完整快照。tree 记录的是目录结构里面是一组条目每个条目要么指向 blob文件要么指向另一个 tree子目录。commit 记录一次提交的作者、时间、提交说明以及这次提交所对应的最顶层 tree。当你执行一次提交时Git 会从工作区读取所有文件内容生成对应的 blob再为目录生成 tree最后把 tree 挂到 commit 上。问题就出在 tree 这一层一个 tree 对象只有在包含条目时才有存在意义。如果一个目录下面什么条目都没有Git 在生成 tree 的时候根本不会为它创建一个节点。换句话说“提交一个空文件夹”在 Git 的语言里就是一个无意义的操作因为它等价于要生成一个没有任何内容的 tree而这样的 tree 对 Git 来说完全没必要存在。我用一个生活化的类比来解释Git 更像是在给每个文件拍照归档它关心的是衣柜里挂了几件衣服、分别是什么款式而不是衣柜本身是不是空着。一个空柜子没有任何需要归档的信息自然就不会出现在记录里。1.2 “文件夹不存在”反而帮你省了很多麻烦想通了这个设计你可能会觉得 Git 这个行为有点反直觉但仔细想想它其实非常合理。一个空文件夹没有任何内容就不存在可对比、可追溯、可恢复的信息。如果每次有人随便新建一个空目录Git 都要在仓库历史里追加一条提交记录那提交历史很快就会堆满无意义的目录噪音。Git 选择只追踪文件内容而非目录本身仓库历史可以保持得更干净别人 clone 下来后也不会看到一长串无用的空目录结构。但工程上确实又有保留空文件夹的需求。最常见的场景是项目运行起来后程序需要往某个目录写文件比如用户上传目录、日志目录、缓存目录但项目代码库里并不想存放这些运行时产生的文件。团队其他成员把仓库 clone 下来后这些目录如果没有被 Git 保留程序第一次启动时可能因为目录不存在而直接报错除非代码里做了自动建目录的逻辑。所以我们需要一种办法把“空目录”固化进仓库。既然 Git 只认文件自然的思路就是往空文件夹里放一个没有任何实际业务意义的占位文件让 Git 眼里这个目录不再空空如也。这个思路听起来简单但它就是业内所有人通用的解法。2. 标准解法用一个占位文件把目录“撑起来”既然 Git 只追踪文件症结找到了接下来就好办了。最简单直接的做法就是在空文件夹里创建一个占位文件。这个文件叫什么由你说了算但无论是 GitHub 上的开源项目、企业内部脚手架模板还是团队协作项目最常见的约定是.gitkeep也有团队使用.keep或者.empty。严格来说.gitkeep并不是 Git 官方规定的特殊文件名它只是一个社区约定。大家一看到这个名字就知道这个文件的作用是“为了让 Git 保留我们这个本来要空着的目录”而不是业务代码的一部分。我到过几个不同团队发现这种命名约定带来的沟通成本很低基本不用解释同事看一眼后缀就能明白。2.1 为什么是 .gitkeep命名背后的约定与历史.gitkeep拆开看就是“给 Git 用的 keep 文件”。很多开源框架在生成项目模板时会在需要保留的目录里放一个.gitkeep。它通常是一个零字节文件内容无关紧要。也有人会在里面写一行说明文字比如“此目录用于存放运行时生成的缓存请勿提交业务文件”这也没有问题。我自己更习惯的作法是占位文件保持为空真正需要说明的东西放在 README 或项目文档里。原因很简单.gitkeep的定位是占位不是一个需要人反复阅读和维护的说明文件。如果团队里有人习惯在占位文件里写注释一旦大家误以为它是配置类文件反而容易产生不必要的讨论。曾经有同事在.gitkeep里写了一堆注释后来被另一个人当成配置文件改了内容结果两个人都觉得很困惑。团队里统一约定占位文件内容一律为空想说明用途就在旁边的 README 里写。2.2 其他命名方案的取舍.keep、.empty 还是 placeholder除了.gitkeep实际项目里还能见到好几种命名.keep很多部署工具和框架里也有出现含义基本一样。.empty直观表示“这个文件夹应该是空的”语义也很清楚。placeholder.txt不隐藏文件对不熟悉 Git 的同事更友好但容易被误认为是一个真正的业务文件。.gitignore在目录里放一个带有特殊忽略规则的文件也能保留目录结构这个方案后面会单独说。对团队来说最重要的不是选哪个名字而是统一约定。我经历过一个项目前端同事喜欢.gitkeep后端同事坚持用.empty结果评审的时候双方都以为对方提交的是垃圾文件来回确认了好几次。后来我们干脆在项目文档里写了一条规定所有需要保留的空目录统一使用.gitkeep这个问题才算彻底消失。既然它是社区事实标准跟主流保持一致是最省心的选择。提示不一定非要在 VSCode 界面里手动创建.gitkeep喜欢用终端的话一条touch 文件夹名/.gitkeep命令就完成同样的效果。方式不重要原理完全一样。3. VSCode 里完整实操流程从创建文件夹到提交验证原理理解了现在进入实操。我教同事做这个操作时发现最大的障碍不是“要不要放一个文件”而是放完之后有一些细节没注意到源代码管理面板一直不出现变化大家就开始怀疑这个方法是不是不灵。下面按我在一个全新仓库里实际操作的完整顺序来写你跟着走一遍就能成功。3.1 第一步确认空文件夹在 VSCode 中确实“不可追踪”打开一个已有的 Git 仓库在资源管理器面板里右键选择“新建文件夹”命名比如uploads。创建完成之后切到左侧源代码管理面板正常情况下你只会看到这个仓库原本的变更列表uploads这个文件夹根本不会出现。如果仓库本身是干净的面板大概率会显示“没有暂存的更改”不会报错也不会出现异常。这一步用来复现问题也确认你的 Git 环境是正常的。很多人走到这里就开始慌张其实不用。刚才我们说过Git 的对比基准是“文件列表”空文件夹在文件列表里没有记录所以无论你怎么刷新它都不会出现在变化列表里。此时 Git 工作正常VSCode 工作也正常只是没有东西需要展示而已。3.2 第二步在空文件夹里创建 .gitkeep 占位文件回到资源管理器面板在uploads文件夹上右键选择“新建文件”输入文件名.gitkeep回车确认。注意文件名是点号开头在 Windows 的资源管理器里可能会被系统隐藏规则挡掉但 VSCode 的文件树默认能显示隐藏文件直接创建即可。创建之后文件内容保持空白不需要写任何东西。这里有一个容易困惑的点为什么 VSCode 里创建了一个隐藏文件源代码管理面板立刻出现了变化因为 Git 在工作区对比时才不管文件是不是隐藏的它发现了一个路径为uploads/.gitkeep的新文件于是认为这个目录有内容需要追踪。说白了Git 能识别的是uploads/.gitkeep这个文件路径目录只是被顺带带入了仓库结构。这个认知很重要后面排查问题时还会用到。3.3 第三步暂存、提交验证目录确实被 Git 记录接下来在源代码管理面板里你会看到uploads/.gitkeep出现在“更改”列表。点文件右侧的加号暂存它也可以直接点击面板顶部的“暂存所有更改”按钮。输入一条清晰的提交信息比如add uploads directory placeholder然后点击提交。提交完成后仓库里就正式记录了uploads/.gitkeep这个文件。但是怎么验证目录真的被记录了呢光看源代码管理面板不够直观因为它现在又是“干净”的状态了。直接开终端验证在 VSCode 菜单栏选择“终端 - 新建终端”执行git ls-files这个命令会列出当前 Git 追踪的所有文件。如果输出中包含uploads/.gitkeep说明目录已经成功进入版本控制。再执行git status看到提示nothing to commit, working tree clean就说明占位文件已经被纳入了某一次提交工作区干净了。3.4 第四步模拟 clone 场景检验目录是否真的保留只提交还不够真正的工程场景是团队成员把仓库 clone 下来之后目录必须存在。你可以用一条命令模拟验证在仓库的上级目录执行git clone 你的仓库地址 测试目录或者本地直接用已经提交的版本验证cd 测试目录 ls uploads你会看到uploads目录存在里面放着.gitkeep。只要目录里有任何文件Git 在 checkout 时就会自动创建这个目录。这里顺便说一个容易踩的坑如果目录里只有.gitkeep没有其他任何说明文件新同事 clone 下来后可能不知道这个目录是干嘛的甚至以为是个误提交的空壳。所以我一般建议旁边的 README 写清楚目录用途把这个坑提前填上。4. 进阶组合空文件夹与 .gitignore 的搭配运用基础用法掌握之后真实项目里更常见的其实不是“纯空文件夹”而是“这个目录要在仓库里保留但目录里的内容不入库”。什么意思呢比如用户上传头像的目录、日志文件目录、临时缓存目录你希望别人 clone 下来时目录在但又不希望每个人本地运行产生的文件都被 Git 追踪一提交就把一堆日志传上去。这种场景要把占位文件和.gitignore搭配起来用逻辑看起来有点绕实际上掌握规则后就非常顺手。4.1 场景一保留目录但忽略其中的全部内容假设项目里需要保留storage/logs这个目录但日志文件全部不入库。第一种写法在仓库根目录的.gitignore文件里加两行规则storage/logs/* !storage/logs/.gitkeep我来解释一下这两行的意思第一行把storage/logs里的所有内容都忽略了第二行用取反符号!把.gitkeep文件单独排除在忽略之外。这样 Git 会忽略这个目录下的一切日志但会保留占位文件目录本身也因此在仓库中可见。这里有一点要注意规则里的storage/logs/*和storage/logs/效果是不同的。如果写成storage/logs/某些情况下会把目录本体也忽略掉效果就没那么理想。推荐使用storage/logs/*加!storage/logs/.gitkeep的组合。第二种写法不修改根目录的.gitignore而是直接在storage/logs目录里面放一个.gitignore文件内容写* !.gitignore它的意思是这个目录下所有文件都被忽略只有.gitignore自己除外。这种做法的好处是规则限定在局部不会污染根目录的全局配置。我个人的经验是一个目录内部的规则优先用局部的.gitignore根目录只放全局性规则两者职责分离。等以后排查问题的时候你不需要翻一大段配置文件就能定位到问题所在。4.2 场景二批量模板与脚手架目录的占位做项目脚手架、初始化模板时经常需要预设多个目录比如public/uploads、runtime/cache、storage/app、resources/images等等。这种时候手动逐个创建太累我通常直接在终端里用一段命令批量搞定mkdir -p public/uploads runtime/cache storage/app touch public/uploads/.gitkeep runtime/cache/.gitkeep storage/app/.gitkeepmkdir -p会循环创建多级目录touch创建对应的占位文件。跑完之后切回 VSCode源代码管理面板里会出现一批新文件全部暂存提交一份脚手架模板的目录结构就定下来了。在 Windows 上不方便使用 bash 命令的话也可以在 VSCode 资源管理器里逐级新建或者使用 PowerShell 里的等价命令。重点真不是用什么工具而是理解原理之后任何方法都只是在做“往空目录放一个文件”这一件事。工具不过是帮你把这个动作批量执行得更快。4.3 场景三如何避免占位文件被误删或误提交内容占位文件毕竟很特殊我在实际项目中遇到过几种麻烦。第一种有的同事在清理代码时觉得.gitkeep是没用文件顺手删掉了结果目录结构跟着消失程序运行时报目录不存在。第二种有同事在.gitkeep里写了一段临时调试内容结果这段内容被打包进了生产环境的产物里。要避免这些问题我有几条很实际的经验在团队约定文档或 README 里写清楚哪个目录是“运行时生成目录”并解释.gitkeep的作用。占位文件尽量保持空内容不要在里面加业务信息。如果担心构建工具把占位文件带进产物检查打包配置是否排除了点开头文件。代码评审时删除.gitkeep的改动需要格外留意。如果确认是要清理目录要评估是否有程序逻辑依赖这个目录存在。我自己还有一个习惯在需要保留的目录里放一个简短 README比如storage/logs/README.md里面写“日志文件由程序运行时写入请勿提交日志内容”。这样新同事 clone 下来之后一看目录里的 README 就明白用途比靠猜强太多。这个成本很低但能让整个团队省很多沟通时间。5. 常见问题与排查技巧实录这一节我整理了在 VSCode 里做“空文件夹提交”时最容易碰到的问题。说实话每个问题单独看都不难但组合在一起没有经验的开发者能纠结一整个下午。我按实际排障经历列一下附带处理思路希望能帮你少走弯路。5.1 问题一创建 .gitkeep 之后源代码管理面板仍然没有变化这个问题排在第一毫不意外。先别怀疑 Git按顺序排查第一确认你是在这个仓库目录下创建的。打开源代码管理面板时注意看一下面板底部显示的仓库路径是不是你的项目目录。有时候终端和界面打开的是不同目录文件建错了位置自然不会有变化。第二检查 VSCode 的设置里是不是配置过files.exclude或者search.exclude。如果你把.*模式排除在外VSCode 的资源管理器可能直接隐藏了点文件但 Git 仍然能识别。这时打开终端执行ls -a看看.gitkeep到底在不在。第三检查.gitignore是否把点文件全部忽略了。有些开发者在全局忽略规则里写了.*这一写就把.gitkeep也忽略掉了Git 又会从“看到文件”变成“看不见文件”。这种问题特别隐蔽如果不查规则对着面板看半天也没结果。第四手动刷新源代码管理面板。VSCode 默认会自动刷新但在某些较大的仓库或者文件监听异常的时候刷新可能不及时。点一下面板右上角的刷新图标或者直接在终端执行git status观察结果变化。5.2 问题二目录里有文件但 Git 还是不识别这种情况多半是目录里的所有文件都被.gitignore规则覆盖了。记住那个核心逻辑Git 看到目录的所有内容都被忽略就会视同空目录处理不会为它建立任何追踪记录。遇到这种情况用git check-ignore -v来定位问题例如git check-ignore -v storage/logs/app.log这条命令会输出具体是哪一条规则、哪个文件里的哪一行把app.log忽略了。看到结果之后你就知道是该调整规则还是该换用占位文件方案。我处理过不少同事的“Git 忽略文件误伤”问题只要用这条命令一查原因立刻水落石出。5.3 问题三提交之后占位文件又被同事删了这类问题属于协作层面的。有时候同事在合并代码时觉得.gitkeep是垃圾文件直接删除并提交目录就从仓库中消失了。遇到这种情况我不建议用技术手段强行阻止删除更有效的做法是在项目约定上做约束。一种可行的方案是在 README 中列出核心目录结构备注哪些目录是程序运行依赖的必须保留。同时在代码评审时重点关注涉及.gitkeep的删除改动。另外如果程序本身有自动创建目录的逻辑比如启动时检查并创建storage/logs这类目录那么即使有人删除占位文件系统也能在运行期自动恢复。这是一个明确的取舍运行时依赖的目录建议程序自动创建纯粹为了目录结构整齐而保留的占位文件才需要靠团队约定来维护。5.4 问题四远程平台显示有目录clone 下来却是空的这个问题很有迷惑性。在远程仓库的网页界面上你也许能看到目录结构里有uploads但 clone 下来之后这个目录却不存在。原因在于远程可视化界面展示的“目录”是从仓库内容反推出来的Git 仓库里保存的永远是目录下的文件不是目录本身。如果最终提交里没有包含uploads目录下的任何文件界面上即使显示过目录也只是基于历史提交或当前工作区状态的一种渲染结果。clone 下来目录消失说明最后那次提交里没有跟踪到任何该目录下的文件。检查的方式很简单用git ls-files | grep uploads看看追踪列表里有没有这个目录下的记录。没有记录就是没有被跟踪跟“空文件夹”的道理完全一致问题根源还是在“Git 只认文件”这一点上。5.5 问题五占位文件会不会让项目里出现不必要的“垃圾文件”有同学担心.gitkeep看起来像是项目里多出的隐藏文件会不会影响构建工具、部署流程或者同事的理解。这种担心很合理因为占位文件本质上就是“为了满足版本控制而存在”的约定文件。处理和缓解方法在前面也提到过在文档中说明它、在打包配置中按需排除、保持内容干净。构建工具一般不会因为一个零字节的隐藏文件出问题除非团队明确要求产物目录零遗漏那时候再额外配置过滤也不迟。此外如果保留的目录将来要放很大的文件比如设计稿素材、模型文件、数据集占位文件本身没有问题真正要考虑的是这些大文件不要直接进入普通 Git 存储。该接入 LFS 的接入 LFS该走对象存储的走对象存储。占位文件的任务只是把目录钉在仓库里至于目录里的内容将来走什么流程是另一套配置了。6. 关于这个操作的几点个人心得我在不同项目里处理过目录结构保留的问题既见过简单方案没做透的坑也见过为了“自动化”把自己绕进去的轮子。最后分享几点个人心得。第一不要试图让 Git 支持“提交空文件夹”。网上偶尔能看到一些脚本或者补丁类的讨论但 Git 的设计有意选择不追踪空目录强行改变这个行为只会让你的工作流越来越偏门实际收益几乎为零。用一个占位文件是全世界 Git 用户都在用的惯例跟大家保持一致才是真正的“超简单”。第二占位文件的命名要跟团队确认清楚。我见过一个仓库里.gitkeep、.empty、.placeholder、.gitignore混用的情况目录结构本身保住了但维护成本上来了。项目文档里一句话就能免掉这些混乱不要在命名这种小事上留隐患。第三在 VSCode 里整个操作流程其实特别简单但多数人的困惑来自“不知道原理就看不到现象背后的意义”。搞懂 Git 的文件追踪机制之后你不但能解决空文件夹问题连带着也会明白为什么有些明明存在的目录却提交不了为什么.gitignore里写错规则后目录会从仓库里消失。这些东西是相通的一次弄明白以后能省力很多。第四如果团队里有完全不熟悉命令行的同事在 VSCode 资源管理器里手动新建.gitkeep是最友好的路径如果你自己习惯终端一条touch命令就能搞定。工具只影响你的操作效率不影响 Git 的底层逻辑。现在再遇到空文件夹你应该不会再疑惑为什么源代码管理面板没有反应了。给它放一个占位文件一切就都顺理成章。