.dockerignore 文件仅控制构建上下文范围，不修改镜像内容；须优先排除本地依赖目录、版本与编辑器元数据、运行时生成物及敏感配置三类文件，以加速构建、提升缓存命中率并防信息泄露。

.dockerignore 文件不修改镜像内容，只控制构建时传给 Docker 守护进程的文件范围。它能减小上下文体积、加快构建速度、提升缓存命中率，并防止敏感信息泄露。

哪些文件必须优先排除

这三类文件最常拖慢构建或带来风险，建议无条件加入：

• 本地依赖目录：如 node_modules/（Node）、venv/ 或 __pycache__/（Python）、target/（Java）。它们不该复制进镜像，应在容器内通过 RUN npm install 等指令安装。
• 版本与编辑器元数据：包括 .git/、.gitignore、.vscode/、.idea/、.DS_Store、Thumbs.db。纯属开发环境产物，上传无意义。
• 运行时生成物与敏感配置：如 logs/、*.log、*.out、.env、.env.local、secrets.json。日志会破坏缓存；环境变量含密钥，绝不能进上下文。

写法细节决定是否真正生效

规则看似简单，但几处容易出错：

Docker Cli

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

下载

• 路径以 / 开头表示从上下文根目录严格匹配，例如 /node_modules 比 node_modules 更安全，避免误匹配子目录里的同名文件。
• ** 支持跨层级匹配，例如 **/*.pyc 可忽略所有深度的 .pyc 文件；dist/** 能覆盖 dist/js/app.js 和 dist/css/style.css。
• 用 ! 做例外恢复：比如先写 *.js 忽略所有 JS，再加 !src/index.js 单独保留入口文件。
• 注释用 # 开头，空行自动跳过；路径区分大小写，不支持正则，只认 glob 通配符（*、?、**）。

快速验证是否起作用

别靠猜测，用这两招确认：

• 执行 docker build --no-cache -t test .，观察日志开头：“Sending build context to Docker daemon …” 后面的字节数。对比加 .dockerignore 前后，明显变小就说明生效。
• 临时在 .dockerignore 最后加一行 * 再构建，如果报错提示找不到 Dockerfile 或关键源码（如 package.json），说明该文件确实被过滤掉了——证明机制在工作。

一个开箱即用的最小化模板

可直接复制到项目根目录（与 Dockerfile 同级），按需删减或补充：

# 忽略开发与系统文件
.git/
.gitignore
.vscode/
.idea/
.DS_Store
Thumbs.db
<h1>忽略本地依赖和构建产物</h1><p>node_modules/
venv/
<strong>pycache</strong>/
dist/
build/
target/
out/</p><h1>忽略日志、临时文件与敏感配置</h1><p><em>.log
</em>.tmp
*.out
logs/
tmp/
.env
.env.local