.dockerignore 是什么
构建上下文里的排除清单：列出的文件与目录不会发送给构建器。它同时解决三个问题：传输更快、敏感文件不会被打进镜像、缓存键更稳定。写法与常见的忽略文件接近，支持通配与例外标记。
基本信息
| 位置 | 构建上下文根目录，文件名固定带前导点 |
|---|---|
| 语法 | 每行一个模式，支持通配、目录匹配与叹号开头的例外 |
| 生效范围 | 所有构建阶段，被排除的文件在任何阶段都不可见 |
| 常见排除项 | 版本库元数据、依赖目录、日志、环境变量文件、构建产物 |
| 注意点 | 它只影响构建上下文，不改变版本库里的文件 |
典型使用场景
- 加速构建：把依赖目录与版本库元数据排除，减少上下文传输与哈希计算
- 防止泄密：把本地环境变量文件、密钥目录排除，避免被打进镜像
- 避免覆盖依赖：排除宿主上的依赖目录，防止复制时覆盖容器里装好的依赖
- 稳定缓存：排除日志与临时文件，避免它们的变动让缓存失效
- 保留例外：整目录排除后单独放行某个必要文件
常用排除清单
常用排除清单
.git
node_modules
**/*.log
.env*
dist
coverage
tests/
!tests/keep.json常见排除项与理由
| 排除项 | 理由 | 不排除的后果 |
|---|---|---|
| 版本库目录 | 体积大且与构建无关 | 上下文传输慢，且可能泄露提交历史信息 |
| 依赖目录 | 会在镜像内重新安装 | 覆盖容器内依赖，原生模块跨平台失效 |
| 环境变量文件 | 含口令与密钥 | 敏感信息进入镜像层，任何拿到镜像的人都能读 |
| 日志与临时文件 | 内容频繁变动 | 缓存频繁失效，构建变慢 |
| 构建产物目录 | 构建时重新生成 | 体积无谓增大，甚至覆盖新产物 |
使用时容易踩的点
- 排除规则对所有阶段生效，某个阶段需要的文件别误排，否则该阶段构建失败
- 被排除的文件仍留在版本库与工作目录里，只是构建时看不到
- 复制指令引用了被排除的文件会直接报错，报错会指出源文件缺失
- 模式写法要与实际路径匹配，不确定时先用构建日志观察上下文大小
- 多环境共用一份排除清单时，注意不要排除某个环境需要的配置文件
排除依赖目录往往是最有收益的一条：依赖在镜像里由包管理器安装，宿主上的版本可能与容器内的运行环境不兼容，复制进去反而制造问题。
凭据类文件必须排除。写进镜像的内容会留在层里，即使后续指令删除，也无法真正抹掉，镜像一旦分发就等于公开。