【AI 总结】Dockerfile reference

Dockerfile Reference | AI 总结

Dockerfile 基础

核心概念

• 定义：Dockerfile 是包含一系列构建指令的文本文件，Docker 可通过读取指令自动组装镜像，指令涵盖基础镜像选择、依赖安装、文件复制、容器配置等操作。
• 执行逻辑：Docker 按 Dockerfile 中指令顺序执行，且必须以 FROM 指令开头（可在其前添加解析器指令、注释或全局作用域的 ARG），FROM 用于指定构建的基础镜像。

格式规范

• 语法结构：# 注释 + 指令 参数，指令不区分大小写，但惯例使用大写以区分于参数。
• 注释规则：以 # 开头的行视为注释（解析器指令除外），# 若在行中其他位置则视为参数；注释不支持行续接符，且行前空格会被忽略（建议避免）。
• 解析器指令：位于 Dockerfile 顶部，影响后续指令处理，不生成构建层，支持 syntax（指定 Dockerfile 语法版本，如 # syntax=docker/dockerfile:1）、escape（设置转义字符，默认 \，Windows 常用 ```）、check（配置构建检查，如 # check=skip=JSONArgsRecommended;error=true），且每个指令仅能使用一次。

核心指令详解

基础构建类

指令	功能	关键说明
FROM	初始化构建阶段，指定基础镜像	支持 --platform 指定平台（如 linux/amd64）、AS <name> 为构建阶段命名，可多次出现以创建多阶段构建
RUN	执行命令创建新层	有 shell 形式（如 RUN apt-get update）和 exec 形式（如 RUN ["echo", "hello"]）； 支持 --mount 挂载缓存 / 密钥 / SSH 等、--network 控制网络环境（default/none/host）、--security 设置安全模式（sandbox/insecure）
ADD/COPY	复制文件到镜像	两者功能相似， ADD 支持远程 URL、Git 仓库及自动解压本地压缩包， COPY 仅复制本地文件 / 构建阶段文件； 均支持 --chown（设置权限）、--link（独立层避免缓存失效）、--exclude（排除文件）等选项

容器配置类

指令	功能	关键说明
CMD	设置容器运行时默认命令	仅最后一个 CMD 生效，支持 exec 形式（如 CMD ["nginx", "-g", "daemon off;"]）和 shell 形式；若用户执行 docker run 时指定参数，会覆盖 CMD 内容
ENTRYPOINT	指定容器可执行程序	优先推荐 exec 形式（如 ENTRYPOINT ["nginx"]），与 CMD 配合时，CMD 作为默认参数；shell 形式会忽略 CMD 和 docker run 参数，且需用 exec 确保信号传递（如 ENTRYPOINT exec top -b）
ENV	设置环境变量	变量在后续构建阶段生效，且容器运行时仍保留，支持 ENV KEY=VALUE 或 ENV KEY VALUE 语法，可通过 docker run --env 覆盖
USER	指定后续指令的执行用户	支持用户名 / 组（如 USER appuser:appgroup）或 UID/GID（如 USER 1000:1000），Windows 需先通过 net user 创建用户
WORKDIR	设置工作目录	后续 RUN/CMD/COPY 等指令基于此目录执行，支持相对路径（相对于前一个 WORKDIR）和环境变量解析（如 WORKDIR $DIRPATH），不存在时会自动创建

元数据与功能类

指令	功能	关键说明
LABEL	添加镜像元数据	键值对形式（如 LABEL version="1.0" description="My Image"），支持多行书写，可通过 docker image inspect 查看，会覆盖基础镜像中同名标签
EXPOSE	声明容器运行时监听端口	仅为文档说明，不实际发布端口，需通过 docker run -p/-P 发布；默认 TCP，可指定 UDP（如 EXPOSE 80/udp）
VOLUME	创建卷挂载点	指定容器内目录作为外部挂载点（如 VOLUME ["/data"]），卷数据在容器间可共享，且主机目录需在 docker run 时指定
ARG	定义构建时变量	用户通过 docker build --build-arg 传递值，支持默认值（如 ARG version=1.0），仅在构建阶段生效，不保留到容器；有预定义变量（如 HTTP_PROXY）和 BuildKit 自动平台变量（如 TARGETPLATFORM）
HEALTHCHECK	配置容器健康检查	支持 CMD 命令检查（如 `HEALTHCHECK –interval=5m –timeout=3s CMD curl -f http://localhost/
STOPSIGNAL	指定容器退出的系统信号	默认 SIGTERM，支持信号名（如 SIGKILL）或数字（如 9），可通过 docker run --stop-signal 覆盖
ONBUILD	添加触发指令	当镜像作为基础镜像时，触发指令在下游构建的 FROM 后执行（如 ONBUILD ADD . /app/src），执行后自动清除，不继承给 “孙代” 构建
SHELL	指定 shell 形式指令的默认 shell	Linux 默认 ["/bin/sh", "-c"]，Windows 默认 ["cmd", "/S", "/C"]，支持多次修改（如 SHELL ["powershell", "-command"]），影响 RUN/CMD/ENTRYPOINT 的 shell 形式

关键使用技巧

环境变量与替换

• 语法：支持 $VAR 或 ${VAR} 形式，${VAR:-word}（VAR 未设置则用 word）、${VAR:+word}（VAR 设置则用 word）等 bash 修饰符，部分版本支持模式匹配（如 ${VAR#pattern} 移除前缀）。
• 生效范围：可在 ADD/COPY/ENV/FROM 等指令中使用，RUN/CMD/ENTRYPOINT 中需通过 shell 处理（exec 形式需显式调用 shell，如 RUN ["sh", "-c", "echo $HOME"]）。

Shell 与 Exec 形式

• Exec 形式：JSON 数组格式（如 RUN ["echo", "hello"]），避免 shell 字符串处理，不自动调用 shell，变量替换需显式调用 shell。
• Shell 形式：普通字符串格式（如 RUN echo hello），自动调用默认 shell，支持行续接符和 Here-Documents（如 RUN <<EOF apt-get update; apt-get install -y vim EOF）。

缓存优化

• RUN 缓存：默认复用缓存，可通过 docker build --no-cache 失效缓存；ADD/COPY 指令若源文件变化，会导致后续 RUN 缓存失效。
• **RUN --mount=type=cache**：挂载缓存目录（如 RUN --mount=type=cache,target=/var/cache/apt apt update），加速包管理器缓存，支持 sharing（shared/private/locked）控制缓存共享。

安全与隐私

• 密钥管理：通过 RUN --mount=type=secret 挂载密钥文件（如 RUN --mount=type=secret,id=aws,target=/root/.aws/credentials aws s3 cp ...），避免密钥 baked 到镜像。
• SSH 访问：RUN --mount=type=ssh 允许构建容器访问 SSH 密钥（如 docker buildx build --ssh default=$SSH_AUTH_SOCK .），支持带密码短语的密钥。