在 Docker 镜像构建中，很多“构建慢、缓存容易失效、CI 上传耗时长”的问题，并不完全来自 Dockerfile，而是源于被忽视的构建上下文。执行 docker build . 时，末尾的点代表当前目录作为构建上下文；其中可用的文件会被构建器处理，COPY 与 ADD 也只能访问上下文范围内的内容。若目录里混有版本历史、依赖目录、日志和本地构建产物，就可能增加传输与校验开销。🚀
一、先理解什么是构建上下文
构建上下文可以理解为“本次构建允许使用的文件集合”。它既可以是本地目录，也可以来自 Git 仓库、压缩包或标准输入。以本地目录为上下文时，其子目录会被递归纳入处理范围，具体机制可参考 Docker 的构建上下文官方文档。
一个常见误区是认为 Dockerfile 没有执行 COPY . .，无关文件就不会产生任何影响。实际上，是否复制进最终镜像与是否进入构建上下文是两个概念。即使文件最终没有出现在镜像中，过大的上下文仍可能拖慢本地处理或远程构建时的网络传输。
二、为什么需要配置 .dockerignore
.dockerignore 用于在构建上下文形成之前排除不需要的文件，其作用类似于 .gitignore，但服务对象是 Docker 构建器。合理配置后，可以减少发送给构建器的数据、降低无关文件导致缓存变化的概率，并避免把敏感配置误复制到镜像中。🔒
对于常见项目，可以从以下内容开始排除：
- .git、.svn 等版本控制目录；
- node_modules、venv、target 等可重新生成的依赖或编译目录；
- 日志文件、测试报告、覆盖率报告和临时缓存；
- 编辑器配置，例如 .idea、.vscode 和交换文件；
- 本地环境变量文件、密钥、证书及其他敏感资料；
- 与容器运行无关的文档、截图和大型测试数据。
三、一份实用的配置示例
下面是一份适用于多数 Web 项目的基础规则，可根据技术栈继续调整：
.git
.gitignore
node_modules
dist
build
coverage
*.log
.env
.env.*
.idea
.vscode
tmp
Dockerfile*
docker-compose*.yml
README*
需要注意，忽略规则并不是越多越好。如果 Dockerfile 需要复制某个文件，而它被规则排除，构建时就会出现文件不存在的问题。对于必须保留的例外项，可使用感叹号重新包含，例如先忽略 *.md，再通过 !README.md 保留指定文件。
四、遵循“默认排除，按需放行”原则
小型项目可以直接维护排除清单；大型单体仓库则更适合采用接近“白名单”的思路：先排除大量无关目录，再明确放行源码、依赖清单和构建配置。这样即使仓库以后新增大文件，也不容易意外进入上下文。⚙️
如果不同 Dockerfile 对上下文的需求差异较大，还可以使用 Dockerfile 专属忽略文件。例如 build.Dockerfile 可搭配 build.Dockerfile.dockerignore。专属文件与 Dockerfile 放在同一目录时，可以覆盖根目录下的通用规则，适合测试、构建和发布等多套镜像流程。相关优先级与语法说明可查看.dockerignore 官方说明。
五、同时优化 Dockerfile 的复制顺序
缩小上下文只是第一步，还应避免过早执行 COPY . .。以 Node.js 项目为例，可以先复制 package.json 与锁文件，安装依赖后再复制源码。这样日常修改业务代码时，依赖安装层仍有机会复用缓存。
FROM node:lts
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
同理，Java 项目可先复制 Maven 或 Gradle 配置，Python 项目可先复制 requirements.txt 或锁文件。核心原则是：变化频率低、执行成本高的步骤放在前面，频繁变化的源码放在后面。Docker 也在构建缓存优化文档中建议保持较小的上下文，并合理安排镜像层顺序。📦
六、避免三类典型错误
- 直接照搬 .gitignore：.gitignore 是很好的起点，但已提交到 Git 的文件未必需要参与镜像构建，而某些未提交的本地生成文件也可能是构建所需内容，因此仍需逐项检查。
- 把敏感文件保护完全交给忽略规则：.dockerignore 能降低误操作风险，但不应作为密钥管理方案。构建密钥应使用 BuildKit 的 secret mount 等专用机制，避免写入 Dockerfile、构建参数或镜像层。
- 为了方便而扩大上下文：在单体仓库中从仓库根目录执行构建虽然便于跨目录复制，却可能引入大量无关文件。应优先缩小上下文，必要时再使用命名上下文或重新规划目录结构。
七、如何检查优化是否有效
执行构建时，可以观察日志中的 transferring context 信息，并比较优化前后的上下文大小与传输耗时。还应在 CI 中进行一次无缓存构建，再进行一次仅修改源码的增量构建，以验证依赖安装等高成本步骤是否成功命中缓存。🔍
建议把 .dockerignore 与 Dockerfile 一起纳入代码审查。当项目新增框架、测试工具或产物目录时，同步更新忽略规则；同时定期检查 COPY 指令，避免通配范围不断扩大。远程构建环境对上下文大小尤其敏感，因为文件需要通过网络发送给构建器。
总结
Docker 构建优化不只是选择更小的基础镜像，也包括管理好“哪些文件可以进入构建流程”。通过缩小构建上下文、精确配置 .dockerignore、按变化频率安排复制顺序，并持续检查缓存命中情况，可以让本地开发和 CI/CD 构建更加稳定高效。最佳实践不是复制一份通用模板后永久不动，而是让忽略规则始终与项目目录、依赖方式和发布流程保持一致。✅
