COPY vs ADD：为什么你应该优先使用 COPY
在编写 Dockerfile 时，COPY 和 ADD 是两个最常用于将文件从主机复制到镜像中的指令。它们看似功能重叠，实则设计理念和行为差异显著。许多开发者习惯性地使用 ADD，认为它“更强大”，但这种选择往往带来隐性风险和维护成本。
Docker 官方明确建议：优先使用 COPY，仅在需要 ADD 的特殊功能时才使用后者。这一原则背后，是对构建可预测性、安全性和透明性的工程追求。
一、COPY：专注且透明的文件复制
COPY 指令的设计哲学是“单一职责”——它只做一件事：将宿主机上的文件或目录复制到镜像的指定路径。
基本语法：
COPY ./src /app/src
COPY package.json ./特点：
- 行为明确：源路径必须存在于构建上下文（build context）中，目标路径在镜像内。
- 不支持自动解压：如果复制一个
.tar.gz文件，它会原样保留，不会被解压缩。 - 不支持远程 URL：只能复制本地文件，无法从 HTTP/HTTPS 地址下载。
优势：
- 透明性高：操作意图清晰，无隐藏逻辑，团队成员能准确理解其行为。
- 构建可预测：由于不涉及网络请求或格式解析，构建过程稳定，不受外部服务可用性影响。
- 安全性强：避免了从不可控来源下载文件的风险。
典型用例：
- 复制应用源码：
COPY . /app - 复制依赖描述文件：
COPY package*.json ./ - 复制配置文件：
COPY nginx.conf /etc/nginx/nginx.conf
二、ADD：功能丰富但暗藏风险
ADD 指令在 COPY 的基础上扩展了两项特殊能力：
- 自动解压：如果源文件是本地的
tar、tar.gz、tgz、bzip2或xz格式，ADD会自动将其解压缩到目标目录。 - 支持远程 URL：可以从 HTTP/HTTPS 地址下载文件并复制到镜像中。
示例：
# 自动解压
ADD app.tar.gz /app/
# 从远程下载
ADD https://example.com/healthcheck.sh /usr/local/bin/风险与问题：
隐藏逻辑导致不可预期行为
当你执行ADD app.tar.gz /app/，Docker 会自动解压。这看似方便，但行为不透明。如果未来该文件不再是压缩包，ADD仍会复制它，但不再解压，可能导致运行时错误。这种“根据文件类型改变行为”的设计，违背了“显式优于隐式”的原则。URL 下载引入外部依赖
使用ADD从远程地址下载文件，会使构建过程依赖外部服务的可用性。一旦该 URL 失效、返回 404 或内容变更，构建就会失败或产生不同结果。这破坏了“一次构建，处处运行”的不可变性原则。缓存失效问题
如果ADD的源是远程 URL，即使文件内容未变，每次构建都可能触发重新下载，导致上层缓存失效，延长构建时间。安全风险
从未经验证的远程地址下载可执行文件，可能引入恶意代码。例如：dockerfileADD https://untrusted-source.org/setup.sh /tmp/ RUN /tmp/setup.sh # 可能执行任意命令
三、最佳实践：何时使用 ADD？
尽管 ADD 存在风险，但在极少数场景下，它的特殊功能仍是必要的：
1. 自动解压本地归档文件
当你有一个预构建的 .tar.gz 包（如第三方 SDK 或静态资源包），且希望在镜像中直接展开，可以使用：
COPY my-app-v1.0.0.tar.gz /opt/
ADD my-app-v1.0.0.tar.gz /opt/但更推荐的做法是显式使用 RUN tar -xzf，以增强可读性：
COPY my-app-v1.0.0.tar.gz /opt/
RUN tar -xzf /opt/my-app-v1.0.0.tar.gz -C /opt && rm /opt/my-app-v1.0.0.tar.gz2. 下载固定版本的二进制工具（谨慎使用）
有时需要在镜像中安装特定版本的 CLI 工具（如 kubectl、aws-cli）。虽然 ADD 支持 URL，但更安全的方式是结合 curl 或 wget 显式下载，并校验 checksum：
RUN curl -Lo /usr/local/bin/kubectl https://dl.k8s.io/release/v1.28.0/bin/linux/amd64/kubectl \
&& chmod +x /usr/local/bin/kubectl四、总结
| 维度 | COPY | ADD |
|---|---|---|
| 核心功能 | 复制本地文件/目录 | 复制 + 自动解压 + 远程下载 |
| 行为透明性 | 高（只做复制） | 低（根据文件类型改变行为） |
| 构建稳定性 | 高（不依赖网络） | 低（URL 可能失效） |
| 安全性 | 高（无远程下载） | 低（可能引入外部恶意内容） |
| 推荐程度 | 优先使用 | 仅在必要时使用 |
核心原则： 使用 COPY 处理所有本地文件复制任务；仅当必须自动解压本地归档文件时才考虑 ADD，避免使用其远程下载功能。
在 TypeScript、Nest、Bun 项目中，源码、package.json、构建脚本等均为本地文件，完全适用 COPY。坚持这一实践，你的 Dockerfile 将更加清晰、可靠、安全，真正体现现代容器化开发的专业水准。