COPY指令默认解引用软链接，复制目标内容而非链接本身；需保留链接时应先COPY再用RUN ln -s显式创建，并确保链接目标在构建上下文内。

Dockerfile 中的 COPY 指令默认会跟随软链接（symbolic link）并复制其指向的目标文件或目录内容，而不是复制软链接本身。这一点与 cp -L 行为类似，容易被忽略，导致镜像中缺失预期的链接结构或意外覆盖内容。

软链接在 COPY 时会被“解引用”

COPY 默认不保留软链接，而是读取链接指向的实际路径，并将目标内容复制进镜像。例如：

• 宿主机上有 ./config -> ./config.prod
• COPY config /app/config 实际复制的是 config.prod 的内容，而非创建一个指向 config.prod 的软链接
• 镜像内 /app/config 是一个普通文件/目录，不是符号链接

需要保留软链接？改用 ADD 或分步构建

ADD 指令在某些旧版 Docker 中对软链接的处理略有不同，但并不保证保留链接（Docker 20.10+ 已统一行为，ADD 同样解引用）。可靠方式是：

• 先 COPY 所有真实文件和目录
• 再用 RUN ln -s 显式重建软链接
• 例如：RUN ln -sf config.prod /app/config

这样可完全控制链接路径、名称和相对性，也便于调试。

注意相对路径和构建上下文范围

软链接若指向构建上下文外的路径（如 ../shared），COPY 会失败并报错 Forbidden path outside the build context。即使链接本身在上下文内，其目标也必须在上下文内，否则解引用失败。建议：

• 构建前确保所有软链接目标都位于构建上下文目录树中
• 使用 find . -type l -ls 检查链接有效性
• 避免跨目录软链接，改用镜像内运行时创建

验证镜像中是否为软链接

构建后可用以下命令确认结果：

• docker run --rm ls -la /path/to/file —— 查看是否显示 l 开头及 ->
• docker run --rm readlink /path/to/link —— 若返回空，说明它不是链接

不要依赖本地文件属性推断镜像内状态，务必实测。