共计 3119 个字符，预计需要花费 8 分钟才能阅读完成。
文章目录[显示]
前言
你有没有遇到过这样的情况：明明 Dockerfile 只有几行，docker build 却慢得离谱？或者构建出来的镜像莫名其妙地膨胀到好几个 GB？
问题很可能不在 Dockerfile 本身，而在你忽略了一个不起眼的小文件——.dockerignore。
这是 Docker 30 天实战系列的第 13 天。读完这篇文章，你将理解 .dockerignore 的工作原理，掌握它的语法规则，并学会在真实项目中用它大幅提升构建效率。
构建上下文：理解问题的根源
要理解 .dockerignore 的价值，首先要理解一个关键概念：构建上下文（Build Context）。
当你执行 docker build . 时，Docker 并不是直接在当前目录运行构建。它的实际流程分两步：
- Docker CLI 将命令末尾指定的路径（这里是
.，即当前目录）下的 所有文件 打包成一个 tar 归档，发送给 Docker 守护进程。 - Docker 守护进程在收到的归档中执行 Dockerfile 中的指令。
这个被打包发送的文件集合就是构建上下文。
关键点在于 " 所有文件 "。假设你的项目目录下有 500 MB 的 node_modules、200 MB 的 .git 历史记录、几百兆的测试数据和日志文件——它们统统会被打包发送，即使你的 Dockerfile 里从未用 COPY 或 ADD 引用过它们。
这就是构建缓慢和镜像臃肿的根源之一。
.dockerignore 的作用很简单：在打包构建上下文之前，告诉 Docker CLI 哪些文件不需要发送。它从源头上解决问题。
基本语法
.dockerignore 文件放在构建上下文的根目录下（通常是项目根目录），每行写一条匹配规则。语法与 .gitignore 类似但不完全相同。
核心规则
# 这是注释，会被忽略
# 忽略所有 .log 文件
*.log
# 忽略 node_modules 目录
node_modules
# 忽略所有 markdown 文件
*.md
# 但保留 README.md（! 表示例外）!README.md
# 忽略根目录下的 temp 目录（不影响子目录中的 temp）temp
# 忽略任意层级下的 __pycache__ 目录
**/__pycache__
# 忽略所有 .env 开头的文件
.env*通配符说明
| 通配符 | 含义 | 示例 |
|---|---|---|
* |
匹配任意非分隔符字符 | *.log 匹配所有 .log 文件 |
? |
匹配单个非分隔符字符 | temp? 匹配 temp1、tempA |
** |
匹配任意层级目录 | **/test 匹配所有 test 目录 |
! |
例外规则，取消前面的忽略 | !README.md 保留该文件 |
规则的顺序很重要
.dockerignore 逐行匹配，后面的规则会覆盖前面的。来看一个例子：
*.md
!README.md这表示：忽略所有 .md 文件，但保留 README.md。如果你把两行顺序颠倒：
!README.md
*.md结果是所有 .md 文件都被忽略，包括 README.md。因为 *.md 是最后生效的规则。
一份实用的 .dockerignore 模板
不同技术栈的项目需要忽略的内容不同，但以下文件几乎在所有项目中都应该被排除：
# 版本控制
.git
.gitignore
.svn
# Docker 相关（避免递归和干扰）Dockerfile
docker-compose*.yml
.dockerignore
# IDE 和编辑器配置
.vscode
.idea
*.swp
*.swo
# 操作系统生成的文件
.DS_Store
Thumbs.db
# CI/CD 配置
.github
.gitlab-ci.yml
Jenkinsfile
# 文档（通常构建不需要）docs
*.md
LICENSE
# 环境和密钥文件（安全考量）.env
.env.*
*.pem
*.key
# 测试相关
test
tests
coverage
.nyc_output针对特定技术栈，还需要补充：
# Node.js 项目追加
node_modules
npm-debug.log
yarn-error.log
# Python 项目追加
__pycache__
*.pyc
*.pyo
.venv
venv
*.egg-info
# Java 项目追加
target
*.class
*.jar
# Go 项目追加
vendor真实效果对比
为了让你对 .dockerignore 的效果有直观感受，我用一个典型的 Node.js 项目做了测试。
项目结构：源代码约 2 MB，node_modules 约 450 MB，.git 目录约 180 MB，其余文件约 20 MB。
| 指标 | 无 .dockerignore | 有 .dockerignore |
|---|---|---|
| 构建上下文大小 | 652 MB | 2.3 MB |
| 上下文传输时间 | 12.8 秒 | 0.1 秒 |
| 总构建时间 | 38 秒 | 22 秒 |
构建上下文从 652 MB 缩减到 2.3 MB，降幅超过 99%。构建时间节省了约 40%。在 CI/CD 环境中每天构建几十次的场景下，这个优化的累积效果非常可观。
三个容易踩的坑
坑一：忽略了 Dockerfile 需要的文件
一个典型错误是写了过于激进的忽略规则，把 Dockerfile 中 COPY 依赖的文件也排除了。
# .dockerignore 中写了
*.json# Dockerfile 中需要 package.json
COPY package.json .
RUN npm install构建会直接报错：COPY failed: file not found。解决方法是用例外规则精确放行：
*.json
!package.json
!package-lock.json坑二：误以为语法和 .gitignore 完全一样
两者的主要区别：.dockerignore 不支持 # 开头的转义（不能用 \# 匹配以 # 开头的文件），也不支持在目录名后面加 / 来特指目录。node_modules 和 node_modules/ 在 .dockerignore 中效果相同。
坑三：.dockerignore 放错了位置
.dockerignore 必须位于构建上下文的根目录。如果你的 docker build 命令指定了不同的上下文路径，.dockerignore 要跟着上下文走，而不是跟着 Dockerfile。
# 上下文是 ./app 目录，.dockerignore 应放在 ./app/.dockerignore
docker build -f ./docker/Dockerfile ./app安全层面的价值
除了性能优化，.dockerignore 还有一个常被忽视的作用：防止敏感信息泄露到镜像中。
即使 Dockerfile 没有显式 COPY 敏感文件，构建上下文中包含的文件理论上可以被中间层缓存捕获。更常见的风险是：团队成员后续修改 Dockerfile 时，不小心用了 COPY . . 这样的宽泛语句，把 .env、私钥、配置文件等一股脑复制进镜像。
在 .dockerignore 中排除敏感文件，等于加了一道安全兜底。这是防御性编码的思维方式。
与多阶段构建配合
.dockerignore 和多阶段构建（Multi-stage Build）是两个互补的优化手段：
.dockerignore优化的是 " 发送给 Docker 守护进程的内容 "——缩小输入。- 多阶段构建优化的是 " 最终镜像中保留的内容 "——缩小输出。
两者结合使用效果最佳。先用 .dockerignore 减少构建上下文体积，加快传输速度；再用多阶段构建确保最终镜像只包含运行时必需的文件。
总结
.dockerignore 是 Docker 生态中最容易被忽视、但投入产出比最高的优化工具之一。创建它只需要两分钟，但能带来三个层面的收益：
- 性能：大幅缩小构建上下文，加快构建速度。
- 安全：防止敏感文件意外进入镜像。
- 可维护性：明确声明了 " 哪些文件与构建无关 "，让项目结构更清晰。
建议从今天起，把 " 创建 .dockerignore" 加入每个新项目的初始化清单，和 .gitignore 同等对待。
下一篇我们将深入探讨 Docker 的网络模型。到时见。
