copy 默认递归复制目录及其全部内容（含隐藏文件和空目录），语法为 copy ，src 须为构建上下文内相对路径，dest 推荐以 / 结尾确保语义明确；注意 .dockerignore 排除影响。

COPY 指令默认就是递归复制目录结构的，不需要额外参数或配置。只要源路径是目录，Docker 构建时会自动将其下所有文件和子目录（包括隐藏文件、空目录）按原层级关系完整复制到镜像中指定的目标路径。

如何正确使用 COPY 复制整个目录

语法格式为：COPY <src><dest></dest></src>，其中 <src></src> 是构建上下文中的相对路径（不能是绝对路径或父目录 ../ 以外的路径），<dest></dest> 是镜像内的绝对路径（推荐以 / 开头）。

• 若 src 是目录（如 ./app），则复制该目录**本身及其全部内容**（不是仅内容）
• 目标路径不存在时，Docker 会自动创建；存在且为目录时，将 src 内容合并放入其中
• 示例：COPY ./config /app/config → 把本地 config/ 目录整体复制为镜像中 /app/config

注意隐藏文件和空目录是否被包含

COPY 会复制所有符合 Unix 文件系统语义的条目，包括以 . 开头的隐藏文件（如 .env、.gitignore）和空目录——前提是它们存在于构建上下文中且未被 .dockerignore 排除。

• .dockerignore 的行为类似 .gitignore，匹配行会阻止对应文件/目录进入构建上下文，COPY 就无法访问它们
• 如果发现空目录没复制成功，先检查该目录是否为空（Docker 不跳过空目录），再确认是否被 .dockerignore 拦截
• 常见误写：COPY ./src/. /app/ —— 这种写法虽能复制内容，但丢失了 src 目录名，且易受 .dockerignore 中 .* 影响

避免意外覆盖或路径错位的技巧

复制目录时容易因目标路径末尾是否带斜杠产生歧义。Docker 官方文档明确：当 dest 以 / 结尾时，Docker 认为其为目录；否则，若 src 是单个文件，dest 被视为文件名；若 src 是目录而 dest 不以 / 结尾，Docker 会尝试创建同名文件（失败并报错）。

• 安全做法：对目录复制，始终让 dest 以 / 结尾，例如 COPY ./app /app/
• 不推荐：COPY ./app /app（无结尾斜杠）——虽然多数情况能工作，但语义模糊，Docker 可能报 “no such file or directory” 错误
• 想把整个目录“移动”进去（保留目录名），就用 COPY ./app /app/；想只复制内容进去（不带 app 目录层），用 COPY ./app/* /app/（但会漏掉隐藏文件）

验证复制结果的方法

构建后可通过运行临时容器检查文件结构：

• docker build -t test-copy .
• docker run --rm -it test-copy ls -la /app
• 或交互式查看：docker run --rm -it test-copy sh，然后用 find /app 或 tree /app（需提前安装 tree）

构建过程中无法直接打印目录树，但可在 Dockerfile 中加调试命令（仅用于开发）：RUN find /app | head -20，帮助确认结构是否符合预期。