.dockerignore 文件作用于构建上下文上传阶段，不改变镜像内容；需置于构建上下文根目录，精准排除本地依赖、编辑器文件、运行时生成物及敏感配置，以提升构建效率与安全性。

.dockerignore 文件不是 Docker Desktop 特有的功能，而是所有 Docker 构建引擎共用的机制——它在 docker build 执行时生效，无论你用 CLI、VS Code Dev Container 还是 Docker Desktop 的 GUI 触发构建。Docker Desktop 本身不提供“图形化配置忽略规则”的入口，真正起作用的只有放在构建上下文根目录下的 .dockerignore 文件。

为什么 .dockerignore 在 Docker Desktop 里没反应？

常见现象：改了 .dockerignore，但构建日志里仍看到 node_modules/ 或 .git/ 被上传；或者镜像体积没变小。原因通常有三个：

• .dockerignore 文件没放在 Dockerfile 所在目录（即构建上下文根目录），比如误放到了子目录或项目外
• 文件名写成 dockerignore 或 .dockerignore.txt，少了一个点或多了后缀
• Docker Desktop 缓存了旧的构建上下文（尤其在反复点击 “Build & Run” 时），实际上传的是上一次打包的压缩包，而非实时读取当前文件系统

哪些路径必须加进 .dockerignore 才算有效？

重点排除三类内容：本地开发产物、运行时生成物、敏感配置。以下规则按优先级排列，复制粘贴即可用（注意斜杠结尾表示只匹配目录）：

Docker Encyclopedia

Docker 文档优先工作流：针对 Docker 特定问题、故障排除、命令规划、镜像/构建、容器/运行时操作及 Compose 等

下载

• /node_modules/ —— Node.js 项目必加，强制容器内 RUN npm install
• /.git/ 和 /.gitignore —— 避免版本元数据污染上下文
• /dist/、/build/、/target/ —— 前端/Java/Python 编译产物，除非你明确要 COPY 它们（多阶段构建中应由 builder 阶段生成）
• /.env、/.env.local、/secrets.json —— 防止密钥泄露到镜像层
• /*.log、/logs/ —— 日志文件与构建无关，且可能极大
• /.vscode/、/.idea/、/.DS_Store、Thumbs.db —— 编辑器和系统临时文件

.dockerignore 的通配符和取反怎么写才不踩坑？

语法虽类似 .gitignore，但几处细节极易出错：

• 以 / 开头表示从上下文根目录精确匹配，例如 /node_modules/ 不会误伤 src/node_modules/；而 node_modules/（无前导斜杠）会跨层级匹配
• **/*.pyc 可匹配任意深度的 .pyc 文件，但 *.pyc 只匹配当前层
• 用 ! 取反时，必须保证“先忽略再恢复”，例如：*.js → !src/index.js 有效；但 !src/index.js 单独写无效（没有前提忽略）
• 不要写 * 或 ** 这种宽泛规则——它可能意外跳过 Dockerfile 或 package.json，导致构建失败

最常被忽略的一点：即使你 COPY . .，只要文件被 .dockerignore 拦截，它就根本不会出现在构建守护进程内存里——既不参与缓存计算，也不会因 COPY 失败报错。所以验证是否生效，最直接的方式是看 docker build 启动时打印的 “Sending build context to Docker daemon” 后面的字节数，对比加规则前后的差异。