1. 简介
Docker 是现代容器化应用开发、交付和部署的核心工具之一。其灵活的体系结构提供了多种方式来定义和配置容器。在构建具有行为一致性的 Docker 应用时，使用 Dockerfile 来定义镜像是一种非常主流的做法。然而，随着 Dockerfile 功能的不断演进，一些高级特性在不同环境和配置下可能会引发问题。
本文将围绕 Dockerfile 中的挂载（mount）功能展开，重点讲解其使用方式以及常见错误“Unknown flag: ‘mount’”的修复方法。我们将回顾 Dockerfile 的基本结构、BuildKit 的引入、挂载类型及其使用场景，并介绍如何正确启用这些高级功能。
我们使用的测试环境为 Debian 12（Bookworm）搭配 GNU Bash 5.2.15，除非特别说明，文中命令应适用于大多数 POSIX 兼容环境。
2. Dockerfile 简介
Dockerfile 是一个文本文件，用于定义如何构建 Docker 镜像。通常，它包含以下内容：
- 指定基础镜像（base image）
- 安装依赖包
- 设置工作目录
- 拷贝文件
- 定义启动命令
一个最简单的 Dockerfile 示例：
FROM debian:latest
CMD ["bash"]
该 Dockerfile 基于最新的 Debian 镜像，并将容器启动命令设置为 bash。
Dockerfile 支持的指令很多，早期版本主要支持如下基础指令：
FROM：指定基础镜像CMD：指定容器启动时执行的命令RUN：构建时执行命令EXPOSE：声明容器运行时监听的端口WORKDIR：设置工作目录COPY/ADD：复制文件到镜像中
随着 BuildKit 的引入，Dockerfile 的功能得到了显著增强，包括支持挂载、缓存、密钥管理等高级功能。
3. Dockerfile 的演进与 BuildKit
Dockerfile 最初仅支持基础功能，但随着 BuildKit 的引入，构建过程变得更加高效和强大。BuildKit 是 Docker 官方推出的构建引擎，具有以下优势：
- 更快的构建速度
- 支持多阶段构建（multi-stage builds）
- 支持构建时挂载（build-time mounts）
- 提升了构建过程的可扩展性和安全性
BuildKit 的一个关键特性就是支持构建时挂载，例如：
- 挂载本地文件或目录
- 缓存依赖
- 安全地传递密钥
- 使用 SSH 访问远程资源
这些功能大大提升了构建灵活性，但也带来了一个常见问题：如果你没有正确启用 BuildKit 或使用了不兼容的语法，就会遇到“Unknown flag: ‘mount’”错误。
4. Dockerfile 挂载详解
挂载（mount）是 Docker 提供的一种机制，允许在构建过程中访问镜像外部的数据。Dockerfile 中的挂载只能通过 RUN 指令配合 --mount 参数实现，语法如下：
RUN --mount=[type=TYPE],option=<value>[...]
默认挂载类型为 bind，但根据需求，也可以使用其他类型：
✅ 支持的挂载类型：
| 类型 | 用途说明 |
|---|---|
bind |
将本地文件或目录挂载到容器中，常用于调试 |
cache |
构建之间共享缓存目录，提升构建效率 |
secret |
安全存储敏感信息，如密码、密钥、令牌等 |
ssh |
通过 SSH 代理转发，访问受保护的远程资源 |
4.1. bind 挂载示例
# syntax=docker/dockerfile:1.4
FROM debian:latest
CMD ["bash"]
RUN --mount=type=bind,source=/tmp/file666,target=/file1
该示例将主机上的 /tmp/file666 挂载到容器内的 /file1 路径下。
⚠️ 注意：挂载的源路径必须存在，否则构建会失败。
4.2. cache 挂载示例（提升构建速度）
# syntax=docker/dockerfile:1.4
FROM node:20-slim
WORKDIR /xpp
COPY package*.json ./
RUN --mount=type=cache,target=/root/npmcache \
npm ci
COPY . .
CMD ["node", "main.js"]
该示例中，我们使用 type=cache 挂载 /root/npmcache，这样 npm ci 的依赖下载会被缓存，下次构建时可复用，加快构建速度。
✅ 提示：适用于 Maven、npm、pip 等依赖管理工具的缓存场景。
4.3. secret 挂载示例（安全传递敏感信息）
# syntax=docker/dockerfile:1.4
FROM debian:latest
RUN --mount=type=secret,id=xecret \
sh -c 'read xecret < /run/secrets/xecret; echo "The secret is: $xecret"'
构建时通过命令行传入密钥：
$ DOCKER_BUILDKIT=1 docker build \
--secret id=xecret,src=xecret.txt \
-t seccon .
构建过程中，xecret.txt 的内容会被挂载到 /run/secrets/xecret，但不会出现在最终镜像中。
✅ 安全性保障：密钥仅在构建阶段可用，不会被暴露到镜像层中。
4.4. ssh 挂载示例（访问远程资源）
# syntax=docker/dockerfile:1.4
FROM debian:latest
RUN apt-get update && apt-get install -y git openssh-client
RUN --mount=type=ssh \
git clone [email protected]:example-user/example-repo.git /xpp
在构建前确保 SSH Agent 已启动并添加了私钥：
$ eval "$(ssh-agent -s)"
Agent pid 66600
$ ssh-add $HOME/.ssh/id_rsa
然后使用 --ssh 参数构建：
$ docker build --ssh default -t sshcon .
这种方式非常适合从私有仓库拉取代码，而无需将密钥硬编码在 Dockerfile 中。
5. 启用 BuildKit 与 Dockerfile 语法版本控制
5.1. Dockerfile 语法声明
BuildKit 支持的高级特性（如 --mount）需要在 Dockerfile 中显式声明语法版本：
# syntax=docker/dockerfile:1.4
否则，Docker 会使用默认的旧版本解析器，导致如下错误：
Error response from daemon: Dockerfile parse error line #: Unknown flag: mount
⚠️ 注意：该行必须放在 Dockerfile 的最开头，且只能是注释形式。
5.2. 设置 DOCKER_BUILDKIT 环境变量
除了声明语法版本外，还需要启用 BuildKit 引擎：
$ DOCKER_BUILDKIT=1 docker build -t my-image .
或者全局导出：
$ export DOCKER_BUILDKIT=1
✅ 提示：如果不设置该变量，即使 Dockerfile 中声明了语法版本，也可能无法启用 BuildKit。
5.3. 修改 Docker 配置启用 BuildKit（推荐）
如果你希望 BuildKit 成为默认构建引擎，可以修改 Docker 的配置文件 ~/.docker/config.json：
{
"features": {
"buildkit": true
}
}
重启 Docker 后生效。这样就不需要每次构建时手动设置 DOCKER_BUILDKIT=1，但仍需在 Dockerfile 中保留 # syntax=... 声明。
6. 总结
本文我们回顾了 Dockerfile 的基本结构和其演进历程，重点介绍了 BuildKit 引入后新增的挂载功能，包括：
bind：本地文件绑定cache：构建缓存secret：安全密钥管理ssh：SSH 代理转发
同时，我们讲解了如何正确启用这些高级功能，避免出现“Unknown flag: ‘mount’”错误。关键点包括：
✅ 声明正确的 Dockerfile 语法版本
✅ 启用 BuildKit 构建引擎
✅ 必要时设置密钥或 SSH 代理
BuildKit 的引入显著提升了 Docker 构建流程的灵活性与安全性，建议在项目中积极采用。但务必注意构建环境的配置，避免因兼容性问题导致构建失败。