Dockerfile 里怎么写注释？

写法：以 # 开头、独占一行，构建时 Docker 完全忽略该行。Dockerfile 不支持行尾注释——指令后面跟 # 会被当成参数的一部分，这是最常见的坑。

正确写法

# 安装运行依赖
RUN apt-get update && apt-get install -y \
    curl \
    ca-certificates

# 应用启动命令
CMD ["python", "app.py"]

注释用途：说明镜像用途、解释某条指令的原因、记录维护者与构建要求。

错误写法（行尾注释）

RUN apt-get install -y curl   # 装 curl

# 装 curl 不会被当注释——它会成为 RUN 命令的一部分传给 shell（这个例子里 shell 恰好把 # 当注释，但 COPY 等指令就会把 # 当文件名处理，直接构建失败）。注释永远独占一行。

续行中的注释

独占一行的注释可以出现在续行指令中，解析器会忽略该行；不要把注释写在续行反斜杠后面：

# 正确：注释在指令上方
RUN apt-get update \
    && apt-get install -y curl \
    && rm -rf /var/lib/apt/lists/*

特殊的 # 行：parser directive

文件最顶部以 # 关键字= 形式出现的行是解析指令，不是普通注释：

# syntax=docker/dockerfile:1
# escape=`

syntax 指定 Dockerfile 语法前端版本（用新特性时需要），escape 改转义符（Windows 镜像常用）。解析指令必须位于开头的解析指令区域；一旦遇到普通注释、空行或构建指令，后续同样形式的行就不会再被当作 parser directive。

常见问题（FAQ）

Q：注释会影响构建缓存吗？
A：普通注释本身不改变解析后的构建指令，但若 Dockerfile 作为上下文文件被 COPY 到镜像，文件字节变化仍可能使该 COPY 及后续缓存失效；解析指令另当别论。

Q：多行注释有吗？
A：没有。每行都得加 #。

Q：.dockerignore 文件里怎么注释？
A：同样用 # 开头独占一行。