add 指令仅对构建上下文内的 tar 系列归档（如 .tar.gz、.tar.xz 等）自动解压，不支持远程 url 或 zip 文件；远程文件需先 add 下载再 run 解压，本地预置归档则可一键解压。
ADD 指令本身不支持“注入网络归档资产”这一说法——它不能主动联网拉取并解压远程归档，但可以从远程 URL 下载压缩包，再在构建上下文为本地时自动解压。关键在于：自动解压仅对本地源文件生效；远程 URL 下载的文件不会被解压，仅复制进镜像。
所以，想实现“下载 + 自动解压”，需分两步走：先用 ADD 下载，再用 RUN 解压。但若归档文件已在构建上下文（如项目目录里），ADD 就能一步到位解压。
✅ 正确理解 ADD 的自动解压能力
ADD 会自动解压以下本地归档格式（仅当 src 是构建上下文中的文件）：
-
.tar、.tar.gz、.tgz -
.tar.bz2、.tbz2 -
.tar.xz、.txz -
.tar.zst（较新版本 Buildah/Docker 支持）
前提是：
- 文件必须存在于 Docker 构建上下文（即
docker build .命令执行目录下） - 目标路径（
dest）是容器内一个已存在或可自动创建的目录 - 不支持对远程 URL 源自动解压（这是常见误区）
⚠️ 远程文件无法自动解压？这样补救
如果你的归档资产托管在公网（如 GitHub Release、对象存储 OSS），不能靠 ADD 一步解压，但可以组合使用：
# 方式1：ADD 下载 + RUN 解压（推荐，清晰可控）
FROM ubuntu:24.04
ADD https://example.com/app-v1.2.0.tar.gz /tmp/app.tar.gz
RUN tar -xzf /tmp/app.tar.gz -C /opt/app && rm /tmp/app.tar.gz
# 方式2：用 curl + tar（更灵活，支持校验、重试、解压到指定结构）
RUN apt-get update && apt-get install -y curl && \
curl -fsSL https://example.com/app-v1.2.0.tar.gz | tar -xzf - -C /opt/app
? 提示：用
curl | tar可避免中间落盘，减少镜像层体积；搭配--no-check-certificate或-k可绕过自签名证书问题（测试环境可用，生产建议配 CA）。
? 实际推荐做法：归档资产预置本地 + ADD 一键解压
最高效、最符合 Docker 最佳实践的方式是：
- 把归档文件（如
vendor-deps.tar.gz）放在项目根目录 - 在
.dockerignore中排除无关内容（防止误传大文件） - 用 ADD 直接引用，享受自动解压和构建缓存优势
# 构建上下文含 vendor-deps.tar.gz → 自动解压到 /app/vendor/ ADD vendor-deps.tar.gz /app/vendor/
这样不仅快（缓存命中率高），还能精准控制解压路径与权限：
ADD --chown=www-data:www-data config.tar.gz /etc/myapp/
❌ 常见错误规避
-
ADD https://.../data.zip /app/→ ZIP 不会被解压（ADD 不识别.zip自动解压，且 ZIP 不在白名单格式中） -
ADD archive.zip /app/→ 即使是本地 ZIP，ADD 也不自动解压（仅支持 tar 系列） -
ADD *.tar.gz /app/→ 不支持通配符，会报错 - 忘记目标目录权限 → 解压后文件属主可能是 root，运行时可能无权读取
需要解压 ZIP？请改用 RUN + unzip：
RUN apt-get update && apt-get install -y unzip && \
unzip -q /tmp/assets.zip -d /app/assets && \
rm /tmp/assets.zip
