.dockerignore 文件不直接参与构建缓存，但通过精简构建上下文间接决定缓存是否命中：未忽略的变动文件会导致上下文哈希变化，从而强制缓存失效；必须排除.git、本地配置、依赖产物、构建输出、敏感文件等；需注意通配符规则、!例外慎用、避免误删COPY路径；可通过上下文体积对比或tar模拟验证效果。
.dockerignore 文件本身不直接参与构建缓存的生成或命中逻辑，但它通过控制哪些文件被发送到 Docker 守护进程（即构建上下文），间接、却非常关键地影响构建缓存的有效性与稳定性。
为什么.dockerignore会影响构建缓存？
Docker 构建时，会把当前目录（或指定路径）下的所有文件打包成“构建上下文”，传给守护进程。如果上下文中包含频繁变动的文件（如 node_modules/、dist/、日志、本地配置、.git 目录等），哪怕它们没被 COPY 或 ADD 指令用到，只要上下文哈希值变了，Docker 就会丢弃后续所有缓存层——因为缓存键（build cache key）依赖于上下文完整性。
也就是说：未忽略的无用文件 = 不必要的上下文变更 = 缓存失效。
哪些内容必须写进.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/
