Dockerfile ADD 下载 tar.gz 后没有生成解压目录

Dockerfile 用 ADD https://…/app.tar.gz /tmp/ 下载成功，下一步访问解压目录却报 No such file or directory。查看构建阶段的文件，只看到压缩包，没有预期的目录。

远程 tar 包与构建上下文中的本地 tar 包，默认处理方式不同。远程 URL 默认下载原文件，本地可识别的 tar 归档默认展开。当前 Dockerfile 语法还提供 ADD --unpack 显式控制这一行为，因此不能笼统地说 ADD 永远不能解压远程包。

先确认缺的是解压步骤

检查出错步骤之前的 ADD 源端究竟是 HTTP(S) URL，还是上下文中的本地文件。若 URL 下载得到的包存在，而后续命令直接操作包内目录，就应核对是否安排了展开。

也要确认压缩包真实内容。文件名以 .tar.gz 结尾，不保证响应体就是归档；下载地址返回登录页或错误页面时，改解包选项无法让它变成有效 tar。归档内部可能还有一层版本目录，展开目的地与包内路径必须一起判断。

下面以 Linux 镜像构建为例。downloads.example.com 是占位域名，必须换成自己核验过的归档地址；示例不代表该地址提供真实文件。

支持 Dockerfile 1.17 时，明确要求展开

--unpack 的最低 Dockerfile 语法版本是 1.17。可用下面的完整示例声明前端版本：

# syntax=docker/dockerfile:1.17
FROM alpine:3.22
ADD --unpack=true https://downloads.example.com/app-1.2.3.tar.gz /opt/app/
RUN ls -la /opt/app

此处的 1.17 是 Dockerfile 前端语法版本，不是 Docker Engine 版本号。构建器必须能够使用这个前端；若报未知选项或无法取得前端镜像，应先核对构建环境支持情况，不能仅凭 Docker CLI 版本判断。

/opt/app/ 是展开目的目录。假设归档内部包含 app-1.2.3/README.txt，结果路径会是 /opt/app/app-1.2.3/README.txt，不会自动去掉包内第一层目录。ls 只是帮助核对结构，实际构建还应检查应用必需的文件，而不只看目录非空。

无法使用该选项时，先准备本地归档

项目暂时不能调整构建器时，可以在受控的下载阶段取得并核验归档，将它作为构建上下文输入，再使用本地 ADD：

FROM alpine:3.22
ADD app-1.2.3.tar.gz /opt/app/
RUN ls -la /opt/app

这要求构建上下文根目录确实包含 app-1.2.3.tar.gz，且它没有被忽略规则排除。归档必须采用构建器识别的 tar 格式；这里展示 gzip 压缩的 tar，不能套用到普通 ZIP 文件。判断是否属于归档依赖文件内容，不是给任意文件改后缀。

下载阶段应按供应方可信校验信息确认内容及版本，再交给构建。不要把未经核验的归档直接展开到包含关键基础文件的目录。选择专用目的目录，并检查包内路径与覆盖范围；本地方案还要避免把不需要的秘密或其他文件一并放进构建上下文。

这两种写法二选一。改成本地源后，构建步骤不再负责远程下载，CI 需要明确准备输入文件；忘记这个步骤会变成另一种“源文件不存在”。

验收最终镜像中的实际路径

在本机测试构建中确认下载或本地输入正确、目标目录包含预期文件，再核对应用引用的完整路径。不要通过忽略后续 mv、cp 的错误来让构建继续，否则可能发布一个缺少程序的镜像。

解压控制只解决文件是否展开，不修复归档内部结构、平台架构或程序依赖。目录出现后程序仍不能运行，需要按新的错误继续定位。

修改前保留原 Dockerfile、固定版本的归档及已验证镜像。新镜像通过应用检查后再按既有流程发布，回退时切回上一可用镜像；不需要为修正构建中的解压行为删除运行数据卷。