概述

你有没有遇到过这种情况：

• Docker 构建越来越慢？
• 镜像越来越大？
• 明明只改了一行代码，却要重新安装依赖？

这些问题，很可能是因为你忘了在项目中添加 .dockerignore 文件

什么是 .dockerignore

.dockerignore 是一个文本文件，放在项目根目录下，用来告诉 Docker：

“在构建镜像时，请忽略这些文件和目录。”

它的作用和 .gitignore 非常相似，但它是为 docker build 服务的

为什么需要 .dockerignore

当你运行 docker build . 时，Docker 会把当前目录下的所有文件打包发送到 Docker 守护进程，这个过程叫做“构建上下文”。

即使你在 Dockerfile 中没有用到某些文件（比如日志、缓存、IDE 配置），它们也会被包含进去。

带来的问题：

问题	后果
文件太多	构建上下文传输慢，尤其在 CI/CD 中
触发不必要的缓存失效	例如 node_modules 变化会导致 COPY . . 层缓存失效
镜像臃肿	包含了调试日志、本地配置等敏感或无用文件
安全风险	可能意外泄露 .env、secrets 等敏感信息

没有 .dockerignore 的后果

假设你的项目结构如下：

my-app/
├── app.py
├── requirements.txt
├── node_modules/     # 100MB
├── __pycache__/      # 缓存
├── .git/             # Git 历史
├── logs/             # 日志文件
├── .env              # 环境变量（含密码）
└── Dockerfile

如果你运行 docker build .，Docker 会把整个目录（可能几百 MB）上传。

更糟的是：

• 即使你只改了 app.py，node_modules 的微小变化也会导致 COPY . . 缓存失效
• 结果：每次都重新安装依赖，构建时间从 10 秒 → 2 分钟

创建 .dockerignore 文件

在项目根目录创建文件：

touch .dockerignore

写入以下内容（适用于 Python 项目）：

# Python
__pycache__
*.pyc
*.pyo
*.pyd
.pytest_cache
.coverage
.python-version

# 虚拟环境
venv/
env/
env.bak/
.venv/

# Node.js
node_modules/
npm-debug.log*
yarn-error.log*
yarn-debug.log*

# 日志和数据库
logs/
*.log
*.sqlite3

# 环境变量（敏感信息！）
.env
.env.local

# IDE 和编辑器
.idea/
.vscode/
*.swp
*.swo

# Git
.git

# Docker
Dockerfile
.dockerignore

# 其他
.DS_Store
Thumbs.db

你可以根据项目类型调整内容。前端项目重点忽略 node_modules，Python 项目忽略 __pycache__，Java 项目忽略 target/ 等

.dockerignore 如何提升构建效率

加入 .dockerignore 后：

1. 构建上下文变小：只上传必要的源码文件（可能从 100MB → 1MB）
2. 缓存更稳定：node_modules 不再被复制，COPY requirements.txt . 和 RUN pip install 层缓存长期有效
3. 构建更快：尤其是 CI/CD 环境，网络传输时间大幅减少
4. 镜像更小、更安全：不包含敏感信息和临时文件

验证效果

你可以通过以下方式验证 .dockerignore 是否生效：

1. 查看构建上下文大小
   Docker 构建时会显示：

Sending build context to Docker daemon  1.534MB

加入 .dockerignore 后，这个值应该明显变小。

2. 检查缓存是否命中
   如果依赖没变，你应该看到：

Step 4/6 : RUN pip install -r requirements.txt
 ---> Using cache

最佳实践

建议	说明
每个项目都应包含 .dockerignore	就像 .gitignore 一样标准
优先忽略大目录	如 node_modules/, dist/, build/, .git/
忽略敏感文件	如 .env, secrets, config.json
使用模板	可参考 github/gitignore 中的 Docker.gitignore

总结

关键点
.dockerignore 虽小，但作用巨大
它能显著提升构建速度、减少镜像体积、增强安全性
它是专业 Docker 使用的“标配”

一句话记住它：

.dockerignore 让 Docker 只看到它该看到的文件。