Docker 构建时如何引用构建上下文之外的文件？

结论：COPY/ADD 的源路径必须在构建上下文之内，这是安全边界，绕不过。但上下文选在哪里是你说了算的**：用 docker build -f docker/Dockerfile . 把上下文设在项目根、Dockerfile 放子目录，就能引用更大范围的文件；BuildKit 还提供 --build-context 具名上下文，直接把另一个目录挂进构建。**

方案一：-f 分离 Dockerfile 与上下文（经典）

项目结构：

project/
├── docker/Dockerfile
├── app/
├── shared-libs/     ← 想引用的目录
└── configs/

docker build -f docker/Dockerfile .

上下文是 project/（命令末尾的点），Dockerfile 里就能 COPY shared-libs /opt/libs。Dockerfile 放哪无所谓，上下文才是关键。

方案二：BuildKit 具名上下文（精准挂载）

docker build --build-context shared=../shared-libs -f Dockerfile .

Dockerfile 里：

COPY --from=shared . /opt/libs

只为所需目录开一扇窗，不扩大主上下文——传输量小、缓存精准。

方案三：多阶段构建复用其他产物

依赖另一个镜像的产物时，不必放进上下文：

FROM myorg/base-builder:latest AS builder
...
FROM runtime
COPY --from=builder /build/dist /app

不要这么干

• ❌ 符号链接指到上下文外：COPY 解析的是上下文内的文件本身，软链出界拷不到真实内容
• ❌ COPY ../shared /app：直接报错 forbidden path

上下文过大的代价

上下文会整个打包发给守护进程——把上下文设在磁盘根目录之类操作会把巨量无关文件塞进构建，慢且可能泄密。配好 .dockerignore（排除 .git、node_modules、日志）。

观测云对照

构建输入可追溯。 CI 里镜像构建的上下文、版本、用时接入观测云后，构建异常（上下文暴涨、缓存全失效）能从指标上发现，而不是等构建慢到无法忍受。

常见问题（FAQ）

Q：tar 流方式（docker build - < Dockerfile）能引用外部文件吗？
A：那种方式上下文为空，COPY 基本不可用，只适合无文件拷贝的镜像。

Q：compose 里怎么控制上下文？
A：build: { context: .., dockerfile: docker/Dockerfile }，两个字段独立指定。

Q：BuildKit 的具名上下文能指向 git 仓库吗？
A：能，--build-context src=https://github.com/org/repo.git，构建时直接拉取。