.dockerignore 文件不直接参与构建缓存，但通过精简构建上下文间接决定缓存是否命中：未忽略的变动文件会导致上下文哈希变化，从而强制缓存失效；必须排除.git、本地配置、依赖产物、构建输出、敏感文件等；需注意通配符规则、!例外慎用、避免误删copy路径；可通过上下文体积对比或tar模拟验证效果。

.dockerignore 文件本身不直接参与构建缓存的生成或命中逻辑，但它通过控制哪些文件被发送到 Docker 守护进程（即构建上下文），间接、却非常关键地影响构建缓存的有效性与稳定性。

为什么.dockerignore会影响构建缓存？

Docker 构建时，会把当前目录（或指定路径）下的所有文件打包成“构建上下文”，传给守护进程。如果上下文中包含频繁变动的文件（如 node_modules/、dist/、日志、本地配置、.git 目录等），哪怕它们没被 COPY 或 ADD 指令用到，只要上下文哈希值变了，Docker 就会丢弃后续所有缓存层——因为缓存键（build cache key）依赖于上下文完整性。

也就是说：未忽略的无用文件 = 不必要的上下文变更 = 缓存失效。

Docker Cli

使用 Docker CLI 构建、运行、停止、检查和管理容器与镜像的助手。用于执行容器相关任务。

下载

哪些内容必须写进.dockerignore？

以下类型文件应默认排除，除非有明确理由保留：

• .git 及其相关文件（.gitignore、.gitmodules 等）——版本元数据与构建无关，且常变动
• 本地开发工具配置：.vscode/、.idea/、.DS_Store
• 依赖安装产物：node_modules/（Node.js）、__pycache__/（Python）、target/（Maven）、build/（Gradle）
• 构建输出目录：dist/、out/、public/（若非用于 COPY）
• 敏感或临时文件：.env、*.log、*.tmp、secrets.json
• 包管理缓存：yarn-cache/、.pnpm-store/（避免污染上下文且无构建价值）

常见陷阱与验证方法

容易忽略的关键点：

• 通配符行为差异：**/node_modules 能匹配子目录，但 node_modules/（末尾带斜杠）只匹配目录，不匹配同名文件；不带斜杠则两者都匹配
• 指令顺序不生效：.dockerignore 是预处理规则，不支持条件判断或“取消忽略”，后写的规则不能覆盖前面的 ! 除外规则（慎用 !）
• 误删必要文件：比如 .dockerignore 中写了 src/，但 Dockerfile 里 COPY src/ /app/src/ 就会失败——要确保被 COPY 的路径未被忽略
• 验证是否生效：运行 docker build --no-cache -q . 并观察首行输出的上下文大小（如 Sending build context to Docker daemon 12.4MB），对比加 ignore 前后的体积变化；也可用 tar -cf - . | tar -t | grep node_modules 模拟上下文打包内容

推荐最小可用.dockerignore模板（通用型）

适用于大多数 Node.js / Python / Go 项目，可按需增删：

.git
.gitignore
.gitmodules
.vscode/
.idea/
.DS_Store
*.log
*.tmp
*.swp
.env
.env.local
node_modules/
__pycache__/
*.pyc
dist/
out/
build/
target/
public/
yarn-debug.log
yarn-error.log
.pnpm-store/