概ね公式ドキュメントの要約です。
パーサーディレクティブ（構文指示）
Parser directives をいい感じな日本語に訳してくれているのを見つけられなかったので、「構文指示」と訳した。
構文指示とはコメントのように # で始まるオプションのことで、Dockerfileの後続行の処理方法に影響する。なので、本記事では構文指示と訳す。構文指示はビルドにレイヤーを追加せず、ビルドステップとしては表示されない。また、ひとつの指示は一度しか使えない。
現在以下の構文指示がサポートされている。
syntaxescape-
check(Dockerfile v1.8.0以降)
構文指示の後には空行を入れるのが一般的。改行文字は構文指示ではサポートされていません。
利用上の注意
必ずDockerfileの先頭に書く
構文指示利用前にコメント、空行、命令が処理されるとBuildKitは構文指示の検索をやめる。
その代わりに構文指示としてフォーマットされていたものはすべてコメントとして扱う。
全ての構文指示はDockerfileの先頭になければならない。
NG例）命令の後に挿入しない
FROM ImageName
# directive=value
NG例）構文指示ではないコメントの後に挿入しているのでコメント扱いになる
# About my dockerfile
# directive=value
FROM ImageName
指示側は大文字小文字を区別して書く
syntax や check のような構文指示のkeyである構文は大文字小文字を区別しない。慣例では小文字を用いる。
しかし、構文指示の指示側であるvalueは大文字と小文字を区別するので、その指示に適した大文字と小文字で書かなければならない。
NG例）
#check=skip=jsonargsrecommended
上記の場合、指示にパスカルケースを使わなければならないので無効となる。
二行に跨がない
NG例）
# direc \
tive=value
同じ指示を複数回使わない
NG例）
# directive=value1
# directive=value2
FROM ImageName
空白は許容される
以下の書き方はすべて同じ意味になる。
すなわち、空白を入れても同じ指示が複数あると無効となる。
#directive=value
# directive =value
# directive= value
# directive = value
# dIrEcTiVe=value
syntax
ビルドに使用するDockerfile構文のバージョンを指定できる。
未指定の場合、BuildKitはバンドルされたバージョンのDockerfileフロントエンドを使用する。
指定することで、BuildKit や Docker Engine をアップグレードしたり、カスタムの Dockerfile 実装を使ったりしなくても、最新の Dockerfile バージョンを自動的に利用できる。
基本的にはこの構文指示を docker/dockerfile:1 に設定することをお勧めする。そうすることで、BuildKit はビルド前に最新の安定版のDockerfile構文を自動的に取得する。
escape
# escape=\
または
# escape=`
Dockerfile 内で文字をエスケープするために使用する文字を設定する。
指定しない場合、デフォルトのエスケープ文字は \ となる。
エスケープ文字は、行内の文字をエスケープするためだけでなく、改行をエスケープするためにも使われる。これにより、Dockerfile の命令を複数行にわたって記述できる。
ただし、escapeの構文指示が Dockerfile に含まれているかどうかに関わらず、RUN コマンド内では行末を除いてエスケープは行われない。
エスケープに ` を指定することはWindows環境下で特に有効となる。PowerShellと同一になる為。
check
# check=skip=<checks|all>
# check=error=<boolean>
上記のように現在二つのオプション（skip, error）があるが、実際には前述したように同一の構文指示を二行に分けて書くことはできない。
skip と error のオプションを組み合わせる場合は、セミコロンで区切って書く。
# check=skip=JSONArgsRecommended;error=true
skip
ビルド時のチェックの評価方法を設定するために使用される。デフォルトでは、すべてのチェックが実行され、エラーは警告として扱わる。
特定のチェックを無効にするには、 #check=skip=<チェック名> を使用する。複数のチェックを無効にする場合は、カンマで区切って指定すればよい。
# check=skip=JSONArgsRecommended,StageNameCasing
逆に、すべてのチェックを無効にするには、 #check=skip=all を使用する。
利用可能なチェック項目を確認するには、ビルドチェックのリファレンスを参照すること。結構数があるので今回は割愛する。
なお、利用可能なチェック項目は Dockerfile の構文バージョンによって異なる。最新のを利用するには、syntaxを使用して、Dockerfile の構文バージョンを最新の安定版に指定すること。
error
デフォルトでは、ビルドチェックが失敗しても警告が出るだけで、ビルド自体はステータスコード 0 で終了する。警告時にビルドを失敗させるには、#check=error=true を設定する必要がある。
# check=error=true
check で error=true オプションを使用する場合、Dockerfile の構文バージョンを特定のバージョンに固定することを推奨する。固定しないと将来のバージョンで新しいチェックが追加されたときにビルドが失敗する可能性がある。
参考
dockerdocs: https://docs.docker.com/reference/dockerfile/