ADD指令不能自动解压远程URL的压缩包，仅对构建上下文内的本地tar类归档（.tar、.tar.gz等）触发解压；远程URL场景下ADD只下载不解压，须用ADD+RUN或多阶段构建显式处理。
ADD 指令**不能自动解压远程 URL 的压缩包**——这是最关键的前提。很多开发者误以为 ADD https://example.com/app.tar.gz /app/ 会下载并解压，实际它只会把压缩文件原样复制进镜像，不会触发任何解压行为。
为什么远程压缩包不被解压
ADD 的自动解压能力仅作用于构建上下文内的本地归档文件（如 ./config.tar.gz）。当源是 HTTP/HTTPS URL 时，Docker 仅执行“下载 + 复制”，完全跳过解压逻辑。这是设计使然，不是版本或平台问题。
- 远程 URL 场景下，ADD 等效于
curl -sSL $URL | tar -xzf - -C /target的语义缺失 - 即使 URL 指向 .tar.gz，镜像中最终只存在一个未解压的二进制文件
- 该限制适用于所有 Docker 版本（包括 26.x），且与宿主机系统无关
正确做法：分两步完成远程压缩包注入
需组合使用 ADD（下载） + RUN（解压 + 清理），确保流程可控、可调试：
-
ADD 下载到临时位置：例如
ADD https://nginx.org/download/nginx-1.25.4.tar.gz /tmp/ -
RUN 解压并移入目标路径：例如
RUN tar -xzf /tmp/nginx-1.25.4.tar.gz -C /usr/src/ && rm /tmp/nginx-1.25.4.tar.gz - 若基础镜像是 Alpine，需提前
RUN apk add --no-cache tar gzip，否则tar -z会失败
替代方案：用多阶段构建预处理远程资源
对安全性或构建复现性要求高时，推荐用 builder 阶段解压，再 COPY 成果：
- 第一阶段用
FROM golang:alpine或通用镜像，ADD + RUN 完成下载解压 - 第二阶段用精简运行镜像（如
FROM nginx:alpine），COPY --from=0 /usr/src/nginx-1.25.4 /usr/src/nginx/ - 避免将构建工具（curl/tar/gzip）和中间产物留在最终镜像中
避坑提醒
以下操作极易导致失败，应主动规避：
- 写成
ADD https://.../app.zip /app/并期待自动解压 → 实际只是复制 zip 文件 - 未检查目标镜像是否含
unzip命令就直接RUN unzip /tmp/app.zip→ Alpine 默认无 unzip - 用
ADD下载后不清理，导致镜像体积膨胀、敏感信息残留 - 依赖远程 URL 持久可用 —— 构建可能因网络抖动或链接失效中断
