容器与云原生 / 系统课时
构建上下文与 .dockerignore
构建上下文与 .dockerignore
docker build 不只读取 Dockerfile,还会读取一个“构建上下文”。如果上下文里混入依赖目录、Git 历史、日志或敏感文件,构建会变慢、缓存更容易失效,也增加误打包风险。本篇会用 .dockerignore 把上下文收窄到真正需要的文件。
学习目标
- 解释
docker build最后一个路径参数为什么决定构建上下文 - 使用
.dockerignore排除无关文件并理解常用匹配规则 - 通过构建验证确认被忽略文件没有进入镜像
先看清什么是构建上下文
命令 docker build -t demo . 最后的 . 表示当前目录就是构建上下文。构建器只能直接使用上下文中可见的文件,以及显式声明的其他构建来源;COPY 和 ADD 不能因为 Dockerfile 放在别处就任意读取主机上的其他路径。

构建上下文过大有三个直接代价:需要处理更多文件;无关文件变化可能让依赖这些输入的缓存失效;如果 Dockerfile 使用宽泛的 COPY . .,还可能把本不该进入镜像的内容复制进去。.dockerignore 就是在上下文进入构建流程前做过滤。
用 .dockerignore 排除无关文件
.dockerignore 通常放在构建上下文根目录,语法类似文件匹配规则。下面的配置排除依赖目录、Git 元数据、敏感文件与普通日志,但通过 !important.log 把一个日志文件重新包含进来。
node_modules
.git
secret.env
*.log
!important.log常用规则包括 *、? 和 ** 通配符;以 ! 开头的规则用于重新包含之前被排除的路径。规则从上到下参与匹配,后面的匹配规则可以改变前面的结果,因此例外规则通常放在更宽泛的排除规则之后。
构建一个可验证的过滤示例
下面的 Dockerfile 复制整个已过滤上下文,并在构建阶段检查:secret.env、node_modules 和 .git 必须不存在,而重新包含的 important.log 必须存在。
FROM alpine:3.22
WORKDIR /app
COPY . .
RUN test ! -e secret.env \
&& test ! -d node_modules \
&& test ! -d .git \
&& test -e important.log
CMD ["sh", "-c", "printf 'context-filter-ok\\n'"]准备最小目录并执行构建:
mkdir -p node_modules .git
printf 'token=do-not-package\n' > secret.env
printf 'ignored\n' > debug.log
printf 'keep-me\n' > important.log
printf 'node_modules\n.git\nsecret.env\n*.log\n!important.log\n' > .dockerignore
docker build -q -t context-filter-demo . >/dev/null
docker run --rm context-filter-demo预期输出
context-filter-ok如果删除 .dockerignore 中的 secret.env 规则,构建会在 RUN test ! -e secret.env 处失败;这说明忽略规则改变的是构建器可见的输入,而不是容器启动后的临时行为。
让上下文保持最小而稳定
选择上下文时不要机械地总用仓库根目录。如果一个仓库包含多个服务,可以从更小的服务目录构建,或使用 -f 指定 Dockerfile,同时把最后一个参数设置为真正需要的上下文。关键判断是:本次构建究竟需要哪些文件,而不是 Dockerfile 放在哪里。
.dockerignore 还应排除会频繁变化但构建不需要的内容,例如测试输出、编辑器缓存、本地日志和依赖缓存目录。这样可以减少无意义的输入变化,让 COPY 相关缓存更稳定。
构建上下文决定了构建器“看得见什么”,.dockerignore 决定了其中“哪些内容值得送进去”。把两者同时设计好,才能真正降低构建传输、缓存失效和误打包成本。