.dockerignore 文件仅控制构建上下文上传范围，不影响镜像内容；须优先忽略本地依赖、编辑器/版本元数据、运行时生成物与敏感配置三类文件。
.dockerignore 文件不是用来“过滤镜像内容”的，而是控制构建时传给 Docker 守护进程的文件范围——它只影响构建上下文（build context）的上传体积，不改变最终镜像里有什么。写对的关键，在于精准排除那些体积大、易变、跟镜像无关的本地文件。
哪些路径必须优先忽略
这三类文件最常拖慢构建、引发缓存失效或泄露敏感信息，应无条件加入 .dockerignore：
-
本地依赖目录：如
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。日志会随构建变动破坏缓存；环境变量含密钥，绝不能进上下文。
写法细节决定是否生效
规则看似简单，但几处容易踩坑：
- 路径以
/开头表示从上下文根目录匹配（例如/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
# 忽略本地依赖和构建产物
node_modules/
venv/
__pycache__/
dist/
build/
target/
out/
# 忽略日志、临时文件与敏感配置
*.log
*.tmp
*.out
logs/
tmp/
.env
.env.local
secrets.json
