# syntax 是什么
Dockerfile 的第一行可以写一条注释形式的语法声明，用来指定解析这个文件的前端（frontend）版本。前端负责把 Dockerfile 翻译成构建图，新语法都在新前端里：RUN --mount、heredoc、COPY --link 等都依赖它。不写声明时用的是引擎内置前端，版本可能偏旧，导致新语法被当成普通命令行处理并报错。
基本信息
| 写法 | # syntax=docker/dockerfile:1（必须是文件最顶部一行） |
|---|---|
| 含义 | 使用最新的 1.x 前端，由构建时拉取 |
| 依赖 | BuildKit：docker buildx 或 Docker 23+ 默认构建 |
| 离线注意 | 需要预先取回前端镜像，否则构建会因拉取失败中断 |
| 查看方式 | plain 进度日志开头会打印实际使用的前端版本 |
| 替代做法 | 写具体小版本如 dockerfile:1.7 以固定行为 |
典型使用场景
- 要用 heredoc 写多行脚本或多行配置文件
- 要用 RUN --mount=type=cache 复用包管理器缓存
- 要用 COPY --link 让复制内容独立成层
- 固定前端版本，避免不同构建机用不同前端产生行为差异
- 排查语法不生效：确认声明位置与前端实际版本
声明与用法
声明与用法
# syntax=docker/dockerfile:1
FROM golang:1.23 AS build
WORKDIR /src
# npm/apt 缓存挂载：命中缓存时重装依赖明显变快
RUN --mount=type=cache,target=/root/.cache/go-build \
go build -o /out/app .
# heredoc 写多行脚本，不需要反斜杠续行
RUN <<'EOF'
set -eux
go version
EOF验证与离线准备
验证与离线准备
# 观察实际使用的前端版本（plain 日志打开后最前面几行会打印）
docker buildx build --progress=plain -t app/web:1.0 . 2>&1 | head -20
# 离线或内网环境：先把前端镜像取回并推入内网仓库
docker pull docker/dockerfile:1
docker tag docker/dockerfile:1 registry.example.com/mirror/dockerfile:1与前端相关的报错
| 报错或现象 | 原因 | 处理方向 |
|---|---|---|
| unknown flag: --mount | 前端过旧或未走 BuildKit | 补 syntax 声明并确认构建走 buildx |
| heredoc 被当命令执行 | 前端不支持 heredoc | 声明 dockerfile:1 以上前端 |
| --link 报未知参数 | 前端低于支持该特性的版本 | 升级前端版本号 |
| 拉取前端失败 | 构建机访问不到仓库 | 预取前端镜像或配置镜像源 |
| 行为与本地不一致 | 各构建机前端版本不同 | 统一写成具体小版本 |
声明必须在文件最顶部，写在 FROM 之后不会生效。用注释语法而不是构建参数，才能保证任何人拿到同一份文件都解析成同一种语法。
写 :1 拿到的是 1.x 最新前端，好处是新特性可用，代价是行为可能随上游变化；对构建稳定性要求极高时写死具体小版本更合适。