挂载为什么会遮蔽目录
容器启动时先准备好镜像文件系统，再按顺序执行卷挂载。挂载点生效后，容器在该路径上看到的是卷的内容，镜像里原本的目录内容并不会被合并进来——它只是被遮蔽了，文件仍在镜像层里，但在容器内不可见。这就是「明明镜像里有配置文件，进容器却找不到」的机制原因，nginx 的 conf.d 与各类应用的 conf 目录最常踩这个坑。
基本信息
| 发生时机 | 容器创建阶段的挂载环节，早于应用进程启动 |
|---|---|
| 行为 | 卷内容覆盖挂载点，不做合并 |
| 典型受害路径 | /etc/nginx/conf.d、/etc/app/conf、/usr/share/nginx/html |
| 不受影响 | 未被挂载的路径与镜像层其它文件 |
| 检测方式 | 容器内 ls 挂载点，对比镜像原始内容 |
现象与写法
现象与写法
volumeMounts:
- name: config
mountPath: /etc/nginx/conf.d # 镜像自带的 default.conf 被遮蔽，不会与卷内容合并
volumes:
- name: config
configMap:
name: nginx-extra # 卷里只有这一个文件，容器里就只能看到它典型使用场景
- 补充配置而非替换：想额外加一个站点配置却把原有配置遮掉，导致默认站点失效
- 挂载整个目录 vs 单个文件：选择 subPath 单文件挂载可保留目录内其他文件
- 多来源配置合并：需要把镜像内置配置与外部配置一起用，必须显式做合并动作
- 静态资源目录：挂载覆盖了默认欢迎页目录，访问根路径时返回 404
- 排障确认：容器内看到「文件丢了」时，先判断是不是挂载遮蔽而非镜像构建错误
三种规避方式
三种规避方式
# 方式一：挂到新目录，再让主配置 include 它（最可控）
# 挂到 /etc/nginx/extra-conf.d，主配置里 include /etc/nginx/extra-conf.d/*.conf
# 方式二：subPath 只挂单个文件，目录其他内容保留
kubectl get cm nginx-extra -o jsonpath='{.data.site}' > /tmp/site.conf # 生成待挂载文件
# 方式三：initContainer 先把镜像原内容拷到 emptyDir，再把 emptyDir 挂回原路径
# cp -a /etc/nginx/conf.d/. /work/conf.d/ && 之后再挂 /work/conf.d规避手段对比
| 手段 | 保留原内容 | 更新是否自动生效 | 适用场景 |
|---|---|---|---|
| 挂到新目录 + include | 是 | 是（卷内容随对象更新） | 追加配置文件，推荐 |
| subPath 单文件挂载 | 是（仅遮蔽该文件） | 否，需重建 Pod | 覆盖单个配置文件的少量场景 |
| initContainer 预拷贝 | 是 | 否，重建时重新拷贝 | 需要与原目录内容合并后整体使用 |
| 直接挂整个目录 | 否 | 是 | 确定要完全替换目录内容时 |
subPath 挂载的文件不会随 ConfigMap 或 Secret 更新而刷新，这是它的已知语义；需要热更新配置时不要把 subPath 与依赖挂载刷新的机制混用，否则会得到「改了配置却没生效」的困惑。
排查顺序建议是：先在容器内确认文件确实不存在，再回到 Pod 定义检查该路径是否被卷挂载覆盖，最后才怀疑镜像构建。挂载遮蔽的现场特征很明确——同一镜像在别的环境的相同路径下有文件。