你肯定遇到过这种场面：本地项目里新建了一个uploads目录，图片传上去跑得好好的，git push完，同事一clone，上传功能直接报错，打开文件树一看——uploads目录根本没拉下来。这不是同事操作失误，也不是 Git bug，而是 Git 一个让无数新手挠头几十次的固有行为：它不追踪空目录。解决方案也简单粗暴，在这个空目录里放一个占位文件，社区惯例叫.gitkeep。这篇文章我就把.gitkeep的原理、用法、坑和最佳实践一次讲透。
不管你是刚学 Git 的初学者，还是已经提交过几千次 commit 的老手，只要你会在项目里初始化目录结构，这篇文章都值得花五分钟看完。其中很多细节属于“文档里不会写、但上班第二天就会被坑到”的那类知识。我会从 Git 的存储模型讲起，把为什么必须用占位文件说清楚，再给你一套可以直接抄作业的落地配置。
1. 为什么 Git 天生无视空目录
1.1 先做个实验，亲眼看看“空目录不存在”
你可以现在就打开终端，试一下最朴素的操作：
mkdir empty_dir git init git status你会发现git status输出的要么是nothing to commit，要么只是提示还没有提交任何内容，绝不会把empty_dir这个目录当成“新增”的东西。你接着执行：
git add empty_dir git status同样干干净净，像这个目录根本不存在一样。
原因并不玄乎。Git 的索引（index）和提交（commit）里记录的，本质上是“文件路径 + 文件内容”的映射关系。目录本身不是一种实体，只有当你往目录里塞进一个文件，Git 才会顺带在对象库里生成路径前缀，也就是我们所说的“目录结构”。换句话说，空目录在 Git 的世界里连“目录”都算不上，它只是一个尚未存在的前缀。放在现实世界里类比，快递单上写“某小区某栋某单元”，但房号不存在，快递员自然默认这单无效。
1.2 空目录为什么会成为开发者的痛点
也许你会问：项目里没有文件，我留一个空目录干嘛？真到要放文件的时候再mkdir不就行了？
问题恰恰出在“运行期才创建”这件事上。大量程序在设计时，默认某个路径一定存在：
- 后端程序启动时要写日志，路径是
logs/ - 用户上传了头像，要保存到
uploads/ - 框架或中间件需要读取
config/下的动态配置 - Docker 构建时要
COPY一个配置目录进镜像 - 测试脚本要往
fixtures/里生成临时文件
本地开发时，你手动mkdir过这些目录，所以一切正常。但其他同事clone下来仓库，目录根本不存在的瞬间，程序可能要自己创建，也可能直接抛FileNotFoundException或者构建失败。为了让每个接手项目的人都能拿到完整可用的目录骨架，你就得想办法把“空目录”也纳入版本控制。.gitkeep就是这个问题的标准答案。
2. 核心思路：用 .gitkeep 打破“空目录”的死结
2.1 .gitkeep 到底是什么
一句话：一个内容可以完全为空、专门用来让 Git 追踪空目录的占位文件。
因为 Git 只追踪文件，那么只要我们保证目录里“有文件”，Git 就会为了记录这个文件，把整条路径一起记录下来。.gitkeep作为一个文件名，本身没有任何魔法，Git 内核并不认识它，也不知道什么“keep”的含义。它的作用只是让“目录里有文件”这件事成立。
你把这个文件命名为placeholder.txt，Git 照样会追踪目录。但社区为什么偏偏用.gitkeep？因为“Git 保持住这个目录”这个语义实在太直白了，任何一个人看到.gitkeep都能猜到它的用途，不会有人误以为它是业务文件而删掉。
2.2 命名为什么是 .gitkeep，而不是 other.txt
家里书架上放一张纸条，纸条上写“本格是空的”，和纸条上写“这是一张纸”效果完全不同。.gitkeep的魅力在于它的自我解释能力。
- 语义清晰：
git+keep，一眼看出这是给 Git 用的占位文件。 - 默认隐藏：以点号开头，
ls不带-a时就看不见，目录视觉上依然干净。 - 风格统一：和
.gitignore、.gitattributes这类点开头的 Git 相关文件保持一致，进目录扫一眼就知道哪些文件属于版本控制基础设施。
如果你图省事放一个keep.txt或text.txt，Git 一样能追踪目录，但后续维护者看到这个文件，心里会打鼓：这文件是干嘛的？能不能删？会不会有程序在读取它？这种“看似普通文件”的占位方式，反而增加了沟通成本。既然团队的最终目的是“让目录别消失”，那就用一个一看就懂的约定名称。
2.3 有替代方案吗
当然有。你可以放README.md，在里面写清楚目录用途；也可以在目录里放一个.gitignore，利用忽略规则占位；甚至可以放任意的空文件。但从“占位”这个目标出发，它们在某个维度上都有些别扭：
README.md适合放文档，但不适合当默默无闻的占位符，而且有些目录并不需要文档。.gitignore占位法能做到工作区非常干净，但它的代价是让一个“过滤规则文件”承担了它本不该承担的职责，新手一看就懵。- 随便放个业务文件，最危险，因为它可能被代码误读、被发布流程误打包。
所以说，.gitkeep不是唯一解，却是语义、成本、兼容性综合得分最高的约定。这也是它能在社区沉淀这么多年的根本原因。
3. 实操：在项目里正确引入 .gitkeep
3.1 最简四步走
假设你要给一个 Java 后端项目保留src/main/resources/logs目录，常规操作如下：
mkdir -p src/main/resources/logs touch src/main/resources/logs/.gitkeep git add src/main/resources/logs/.gitkeep git commit -m "chore: keep logs directory" git push你可能会问，touch一下就够了吗？对，.gitkeep不需要内容。Git 只关心“这个文件存在”，不关心文件里写了什么。
等到同事或者 CI 服务clone这个仓库时，再执行：
git clone <repo-url> new-project ls -la new-project/src/main/resources/logs就能看到.gitkeep安安静静躺在里面，logs目录也保住了。这一步验证做完，你才算真正体验到了占位的效果。
3.2 目录能被跟踪的关键判断标准
很多时候你已经touch了.gitkeep，目录也在本地存在，但推上去就是没效果。这时候别盯着文件管理器看，直接看 Git 索引：
git ls-files --stage如果输出里包含了类似这样的行：
100644 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 0 src/main/resources/logs/.gitkeep说明.gitkeep已经被 Git 追踪，目录结构一定也会随着提交分发出去。这个方法比肉眼判断可靠得多。
也可以只看某个目录：
git ls-files src/main/resources/logs只要有输出，就说明目录的路径被记录在了版本控制里。
提示：
e69de29...是空文件的 SHA-1 哈希值，它大量出现在各种空占位文件中，看到它你就知道这个文件没有任何内容。
3.3 要不要给 .gitkeep 写内容
我的建议是：留空，或者只写一行注释。
留空最安全，因为 .gitkeep 最怕被误认为是业务文件。一个内容为空的文件，大家一看就知道是占位符，删起来没有心理负担。如果你真想告诉后来人“这个目录干嘛用的”，应该单独放一个README.md，而不是把说明塞进.gitkeep。
举一个反面例子：有人喜欢在.gitkeep里写“勿删，程序启动会往此目录写日志”。这句话看着贴心，但问题在于，不同的人对“勿删”理解不同，有人觉得“那就不要动它”，有人觉得“提交了就行，本地删掉无所谓”。一旦这个文件承载了太多信息，就会产生各种歧义。一个文件只做一件事，占位就老老实实占位。
4. .gitkeep 和 .gitignore：千万别当成一回事
4.1 两个文件的职责边界
我见过太多人把.gitkeep和.gitignore混在一起讲。实际上它俩的职责完全不同，一个管“保留”，一个管“排除”。
.gitkeep：目的是占位，让 Git 追踪一个空目录。.gitignore：目的是过滤，让 Git 忽略某些文件和目录。- 两者可以配合使用，但绝对不能互相替代。
一个典型的错误示范：有人把根目录的.gitignore写成：
**/.gitkeep本意可能是想忽略某些临时目录，结果顺手把占位文件也忽略了。于是.gitkeep从未被跟踪，空目录依然进不了仓库。等你clone下来才发现目录丢了，又得排查半天。
4.2 用 .gitignore 占位的方案为什么有人用
在.gitkeep流行之前，不少老项目会在空目录里放一个.gitignore，内容是这样的：
* !.gitignore意思是：忽略这个目录下的所有文件，除了.gitignore自己。这个方案有个好处：目录里唯一可见的 .gitignore 本身是隐藏文件，仓库看起来几乎没有多余内容，工作区非常干净。
但它有一个隐蔽的坑：如果以后有人真的往这个目录里放了一个业务文件，比如config.json，因为*规则的存在，这个config.json会被静默忽略。开发者本地跑着没事，git status里根本看不到这个新文件，结果push之后，同事clone下来缺了配置，程序直接跑不起来。排查半天才发现，罪魁祸首就是那个用来占位的.gitignore。一个文件承担了两个职责，迟早会误伤。
4.3 实际项目中我推荐的组合
我自己在项目里是这么区分使用的：
| 占位方式 | 核心作用 | 优点 | 缺点 | 推荐度 |
|---|---|---|---|---|
.gitkeep | 纯占位 | 语义清晰、不误伤后续文件 | 会留下一个隐藏文件 | 高 |
.gitignore占位法 | 占位 + 忽略 | 工作区干净 | 语义混乱、可能误伤业务文件 | 中 |
README.md | 占位 + 文档 | 能解释目录用途 | 文件不够“隐形”，有时不想提交文档 | 中 |
| 裸空目录 | 什么都不做 | 没有 | Git 不跟踪，clone 后消失 | 低 |
如果你的诉求只是“这个目录必须存在于仓库里”，别犹豫，用.gitkeep。
如果这个目录将来要放很多杂七杂八的文件，但只有其中一部分需要进仓库，那才轮到.gitignore出场。两者也能共存，比如目录里有.gitkeep，旁边再放一个.gitignore，一个管占位，一个管过滤，各司其职。
注意：千万不要在
logs/*这类规则里把.gitkeep一起忽略掉。如果确实要忽略目录内容但保留占位，可以这么写：
logs/* !logs/.gitkeep规则顺序上，取反规则要放在忽略规则之后，才能生效。
5. 真实场景与落地经验：我是怎么用它的
5.1 高频场景清单
- 后端项目：
logs/、uploads/、backup/、temp/，程序需要运行时目录。 - Python 项目：
data/、models/、static/、media/，很多库会直接在当前目录找数据文件。 - 前端项目：
public/images、src/assets/icons，预留给设计稿切图或静态资源的目录。 - Docker 构建：
COPY required_dir ./dir时，如果源目录在仓库里存在，构建过程更稳，也不会触发 COPY 源不存在的报错。 - CI 缓存目录：比如
build/cache/，提前占位可以避免某些脚本在缓存目录不存在时行为不一致。
以上这些场景，只要目录在仓库里被.gitkeep保住了，任何人 clone、任何 CI 环境拉代码，目录结构都会和本地一模一样。你就不会遇到“我本地能跑，你那边怎么不行”的经典甩锅对话。
5.2 经验1：如果只忽略内容，不想忽略目录
实战里最常见的一个配置组合是这样的：
logs/* !logs/.gitkeep这样做的效果是：
logs目录本身被跟踪，因为.gitkeep存在。logs目录下运行时生成的日志文件全部被忽略，不会污染 Git 状态。- 以后新增日志规则，只需要单独加
*.log等后缀即可。
要特别提醒的是，logs/*和*.log不一样。logs/*匹配的是logs目录下的所有条目，但它不会递归匹配更深层级的目录。如果你的日志系统还会生成二级目录，请按需调整。日常使用中，这个组合已经能覆盖绝大多数需求。
5.3 经验2：模板仓库里批量生成 .gitkeep
如果你在维护项目脚手架，或者需要一次性为新项目铺好目录结构，手动touch效率太低了。我通常会写一段小脚本：
#!/usr/bin/env bash for dir in logs uploads backup temp; do mkdir -p "$dir" touch "$dir/.gitkeep" donePython 版本也很简单：
from pathlib import Path for name in ["logs", "uploads", "backup", "temp"]: p = Path(name) p.mkdir(exist_ok=True) (p / ".gitkeep").touch()脚本跑完，目录结构和占位文件一次性成型。之后只管git add .再提交。模板仓库里提前埋好.gitkeep，能让每一个基于模板创建的项目自动继承正确的目录骨架，省去后续人肉补目录的麻烦。
5.4 经验3：GitHub 等平台怎么显示 .gitkeep
很多新手第一次提交.gitkeep后，跑到 GitHub 网页上一看，目录还在，但点进去看不到.gitkeep，以为提交失败了。其实平台只是默认隐藏了点开头文件，需要勾选显示隐藏文件，或者在地址栏直接访问目录路径才能看到。
我同事当年就因为这个差点把好好的提交回滚掉。所以遇到“网页上看不到”的情况，先用git ls-files确认，再决定要不要动手。版本控制的世界里，命令输出永远比界面显示更可靠。
6. 常见问题与排查技巧实录
6.1 问题速查表
| 现象 | 原因 | 解决办法 |
|---|---|---|
| clone 后目录消失 | .gitkeep没被提交 | 检查git ls-files，补提交 |
.gitkeep提交了但网页看不到目录 | 平台隐藏点开头文件 | 显示隐藏文件，或直接访问路径 |
.gitkeep提交了但 checkout 后目录不存在 | 被.gitignore规则忽略 | 用git check-ignore -v查哪条规则 |
| 清空工作区后目录也没了 | 占位文件是 ignored 状态且未跟踪 | 改用.gitkeep并确保它被跟踪 |
| 目录里新文件不显示在 git status | *忽略规则误伤 | 删掉占位.gitignore，或新增取反规则 |
| 无法确定占位是否生效 | 忘了查索引 | git ls-files <路径>有输出即生效 |
6.2 排查专用命令
遇到“占位失效”类问题，我一般按下面这三条命令依次排查：
git status --short git ls-files -v src/main/resources/logs git check-ignore -v src/main/resources/logs/.gitkeepgit status --short：看.gitkeep有没有被正常添加。git ls-files -v：看这个文件是不是已经被 Git 追踪，前面是H表示正常跟踪。git check-ignore -v：如果这个文件被忽略了，会告诉你“被哪条规则、哪个文件忽略”。这个命令能直接揪出**/.gitkeep这种坑人写法。
只要把这三条命令的输出组合起来，80% 的“目录消失”问题都能当场定位。
6.3 一个让我印象深刻的排障事故
去年帮一个项目排查 CI 构建失败，流水线脚本在构建前会执行git clean -fd，然后发现某个模块的解压目录找不到了。查来查去，最后发现项目里原本有一个temp/目录，里面放的占位文件是.gitignore，但它的内容写的是：
* !.gitignore按道理说，这个.gitignore被提交后是 tracked 的，git clean不该删它。但问题出在后来有人优化规则时，把这个目录从 Git 里git rm --cached了，于是它变成未跟踪状态，随后被人执行git clean -fd整个清理掉，目录消失，构建脚本开始报错。
如果最初用的是.gitkeep，它作为 tracked 文件天然不会被git clean碰，就不会踩到这个坑。一个纯粹的占位文件，最大的价值就是它只做占位，不参与任何忽略逻辑，也不容易被误操作卷进清理范围。
最后再分享一个我个人的小习惯：在创建新项目目录结构时，我会在每个必须保留的空目录里放一个.gitkeep，并在根目录的 README 里列一张目录说明表。这个组合的维护成本极低，后来人只看一眼文档就能知道每个目录是干嘛的，哪些是运行时生成的，哪些是版本控制必须保留的。如果你现在正被“clone 之后某个目录神秘消失”折磨，不妨今天就打开项目，给那个目录补上一个.gitkeep。
