跳转至

gitignore 实战案例整理

下面通过一组典型案例，展示 .gitignore 在实际项目中的常见使用方式。每个案例都只关注实际场景和写法，帮助快速理解规则的应用。

忽略某一类文件

在很多项目中，会产生大量临时文件，例如日志、缓存、编辑器临时文件等。这类文件通常不需要提交到 Git 仓库。

例如：

*.log
*.tmp
*.cache
*.bak

在这个规则下，仓库中所有以 .log、.tmp、.cache、.bak 结尾的文件都会被忽略。

例如项目中出现：

server.log
error.log
temp.tmp
backup.bak

这些文件都不会被 Git 纳入版本管理。

这种写法非常适合处理 某一类型的文件。

忽略某个固定文件

有些文件虽然只有一个，但通常包含敏感信息或本地配置，不适合提交到仓库。

例如：

.env
config.local.json

假设项目结构如下：

project
 ├─ src
 ├─ .env
 └─ config.local.json

Git 会忽略：

.env
config.local.json

这类规则通常用于：

  • 本地环境变量

  • 私密 API Key

  • 本地调试配置

忽略某个目录

在实际开发中，一些目录是自动生成的，例如依赖包目录、构建输出目录等。这些目录往往体积很大，也没有必要提交。

例如：

node_modules/
dist/
.cache/

如果项目结构是：

project
 ├─ node_modules
 ├─ dist
 ├─ src
 └─ README.md

Git 会忽略：

node_modules/
dist/
.cache/

其中的所有文件和子目录都会被忽略。

这种规则是最常见的一类 .gitignore 写法。

只忽略根目录中的某个目录

有时候项目中不同层级会出现同名目录，但只希望忽略根目录的那一个。

例如：

/node_modules/
/dist/

假设项目结构：

project
 ├─ node_modules
 ├─ dist
 └─ src
     └─ dist

Git 会忽略：

project/node_modules
project/dist

但不会忽略：

src/dist

因为规则前面的 / 表示 只匹配仓库根目录。

忽略任意层级的某类目录

在大型项目中，有些目录可能出现在不同层级。此时可以使用 ** 来匹配任意目录层级。

例如：

**/cache/
**/temp/

如果项目结构如下：

project
 ├─ cache
 ├─ src
 │   └─ cache
 └─ tools
     └─ temp

Git 会忽略：

cache/
src/cache/
tools/temp/

这种写法适合用于：

  • 缓存目录

  • 构建缓存

  • 编译临时文件夹

忽略目录内容但保留某个文件

有些项目需要保留目录结构，但不希望目录中的文件被提交。常见做法是保留一个占位文件。

例如：

logs/
!logs/
logs/*
!logs/.gitkeep

假设目录结构：

project
 └─ logs
     ├─ app.log
     ├─ error.log
     └─ .gitkeep

最终 Git 只会保留：

logs/.gitkeep

而忽略：

logs/app.log
logs/error.log

这种方式通常用于：

  • 日志目录

  • 上传目录

  • 临时数据目录

全部忽略，再通过白名单放行

有些项目只希望同步少量重要文件，其余全部忽略。这时可以先忽略所有内容，再逐步放行需要的部分。

例如：

*

!src/
!docs/
!README.md

!src/**
!docs/**

假设项目结构：

project
 ├─ src
 │   └─ app.js
 ├─ docs
 │   └─ guide.md
 ├─ test
 │   └─ test.js
 └─ README.md

Git 最终只会跟踪：

src/app.js
docs/guide.md
README.md

而忽略：

test/

这种模式适合：

  • 只同步部分内容的仓库

  • 过滤掉大量无关文件

  • 保持仓库结构简洁

保留目录但忽略所有生成文件

有些项目需要保留一个输出目录，但里面的文件都是自动生成的。

例如：

build/*
!build/.gitkeep

项目结构：

project
 └─ build
     ├─ output.js
     ├─ bundle.css
     └─ .gitkeep

Git 会忽略：

build/output.js
build/bundle.css

但保留：

build/.gitkeep

这样仓库中仍然能保持目录结构。

多模块项目中的忽略策略

在多模块项目中，经常会有多个模块同时存在，每个模块都会生成自己的构建文件。

例如：

**/build/
**/dist/
**/*.log

如果项目结构：

project
 ├─ moduleA
 │   ├─ build
 │   └─ dist
 └─ moduleB
     └─ build

Git 会忽略：

moduleA/build
moduleA/dist
moduleB/build

这种规则适合：

  • 多模块项目

  • 单仓库多应用结构

  • 自动构建系统

总结

通过以上案例可以看到，.gitignore 在实际项目中通常围绕几种典型需求展开：

  • 忽略某类文件（日志、缓存、临时文件）

  • 忽略固定配置文件

  • 忽略构建输出目录

  • 保留目录但忽略内容

  • 使用白名单方式控制仓库内容

  • 在多层目录结构中统一忽略某些文件夹

掌握这些常见模式后，基本可以覆盖绝大多数项目中的 .gitignore 使用场景。