Dockerfile 改 APP_VERSION=2.5 后 build 缓存全失效 ARG 和 --build-arg 怎么只失效一层

现象:改版本号 DoCker build 缓存全失效

Dockerfile 里写 ENV APP_VERSION=v1.0.0,每次改 .env 里的版本号重新 build,后面所有层都要重跑,构建从 30 秒变成 3 分钟。换成 ARG 后缓存只在参数变化的那一层失效,后面的 COPY、RUN 还能复用。

ARG 和 ENV 的核心区别

ENV 在镜像运行时仍存在,容器里 printenv 能看到;ARG 只在 build 阶段有值,运行时就没了。ENV 写在 RUN 前面值变了会让后面所有缓存失效,ARG 控制缓存粒度更精确。

# 坏写法:ENV 放 RUN 前面,版本变化让所有缓存失效
FROM python:3.12
ENV APP_VERSION=2.5
RUN echo "Building " > /app/info.txt
COPY . /app
RUN pip install -r requirements.txt

# 好写法:ARG 在需要位置用,缓存粒度更细
FROM python:3.12
ARG APP_VERSION=2.5
RUN echo "Building " > /app/info.txt
COPY . /app
RUN pip install -r requirements.txt

--build-arg 覆盖默认值

build 时用 --build-arg APP_VERSION= 覆盖,CI/CD 里传 Git tag 特别方便。ARG 只在 build 时有效,运行时需要用 ENV 转一下。

# 运行时也要版本号
ARG APP_VERSION=2.5
ENV APP_VERSION=

缓存失效排查

缓存失效时看 build 输出里哪些步骤没命中 cached,通常是 ARG/ENV 值变了、COPY 文件变了、或 RUN 命令变了。先排除这三类,再看 .dockerignore 是不是漏了不该忽略的文件。

总结:Dockerfile 里 build-time 变量用 ARG 而不是 ENV,缓存粒度更细。运行时需要的值再转成 ENV。ARG 用 --build-arg 覆盖,CI/CD 传 Git tag 方便。

您可以还会对下面的文章感兴趣: