Dockerfile指令大全 - 语法说明与示例

点击左侧跳转分类；点击指令/示例即可复制。推荐优先 COPY 而非 ADD，CMD/ENTRYPOINT 用 JSON 数组（exec）形式。

基础指令

指令	说明	示例
`FROM image[:tag]`	指定基础镜像；必须是首条有效指令（ARG 除外）	`FROM eclipse-temurin:17-jre`
`FROM image AS name`	多阶段构建：给本阶段命名，供后续 COPY --from 引用	`FROM maven:3.9-eclipse-temurin-17 AS build`
`LABEL key=value`	给镜像加元数据（维护者、版本、描述等）	`LABEL org.opencontainers.image.title="myapp"`
`MAINTAINER name`	已废弃，请用 LABEL maintainer=...	`LABEL maintainer="dev@example.com"`

执行命令

指令	说明	示例
`RUN command`	构建时在镜像里执行命令（安装依赖、编译等）	`RUN apt-get update && apt-get install -y curl`
`RUN ["exec", "arg"]`	JSON 数组形式（exec 形式，不经 shell）	`RUN ["npm", "ci", "--omit=dev"]`
`CMD command`	容器启动默认命令；可被 docker run 参数覆盖；一个 Dockerfile 只保留最后一条	`CMD java -jar /app/app.jar`
`CMD ["exec", "arg"]`	推荐：exec 形式，PID 1 为应用本身，信号可正确传递	`CMD ["java","-jar","/app/app.jar"]`
`ENTRYPOINT command`	容器入口点；常与 CMD 搭配（ENTRYPOINT 固定，CMD 作默认参数）	`ENTRYPOINT ["nginx", "-g", "daemon off;"]`
`ENTRYPOINT ["exec", "arg"]`	exec 形式入口；docker run 的参数会追加到 ENTRYPOINT 后	`ENTRYPOINT ["./entrypoint.sh"]`

文件复制

指令	说明	示例
`COPY src dest`	从构建上下文复制文件/目录到镜像（推荐日常使用）	`COPY target/app.jar /app/app.jar`
`COPY --chown=user:group src dest`	复制同时改属主（需基础镜像支持）	`COPY --chown=app:app . /app`
`COPY --from=stage src dest`	从其他构建阶段或镜像复制（多阶段构建核心）	`COPY --from=build /src/target/app.jar /app/app.jar`
`ADD src dest`	类似 COPY；额外支持本地 tar 自动解压、远程 URL（一般更推荐 COPY）	`ADD rootfs.tar.gz /`
`ADD https://... dest`	从 URL 下载到镜像（缓存与可复现性较差，慎用）	`ADD https://example.com/tool.tgz /tmp/`

环境与路径

指令	说明	示例
`ENV KEY=value`	设置环境变量（构建与运行时都可见）	`ENV JAVA_OPTS=-Xms256m -Xmx512m`
`ENV KEY=value KEY2=value2`	一次设置多个环境变量	`ENV NODE_ENV=production PORT=8080`
`ARG name[=default]`	构建参数，仅构建期可用；可用 --build-arg 传入	`ARG APP_VERSION=1.0.0`
`ARG name / ENV name=$name`	把构建参数固化进运行环境的常见写法	`ARG VERSION ⏎ ENV APP_VERSION=$VERSION`
`WORKDIR /path`	设置工作目录；后续 RUN/COPY/CMD 相对此路径；不存在会自动创建	`WORKDIR /app`
`USER user`	后续指令与容器默认以该用户运行（提高安全性）	`USER app`
`USER uid:gid`	用 UID/GID 指定用户	`USER 1000:1000`

网络与存储

指令	说明	示例
`EXPOSE port`	声明容器监听端口（文档性；不会真正发布端口）	`EXPOSE 8080`
`EXPOSE port/udp`	声明 UDP 端口	`EXPOSE 53/udp`
`VOLUME ["/data"]`	声明挂载点；运行时未 -v 也会创建匿名卷	`VOLUME ["/var/lib/mysql"]`
`VOLUME /data`	字符串形式声明卷	`VOLUME /data`

健康检查与信号

指令	说明	示例
`HEALTHCHECK CMD command`	定义健康检查命令；失败会标记 unhealthy	`HEALTHCHECK CMD curl -f http://localhost:8080/health \|\| exit 1`
`HEALTHCHECK --interval=30s --timeout=3s --retries=3 CMD ...`	自定义检查间隔/超时/重试	`HEALTHCHECK --interval=30s --timeout=3s --start-period=20s --retries=3 CMD wget -qO- http://127.0.0.1:8080/health \|\| exit 1`
`HEALTHCHECK NONE`	禁用继承自基础镜像的健康检查	`HEALTHCHECK NONE`
`STOPSIGNAL signal`	容器停止时发送的信号（默认 SIGTERM）	`STOPSIGNAL SIGTERM`

Shell 与构建技巧

指令	说明	示例
`SHELL ["executable", "params"]`	覆盖默认 shell（影响后续 shell 形式的 RUN/CMD/ENTRYPOINT）	`SHELL ["/bin/bash", "-c"]`
`ONBUILD instruction`	当本镜像被其他 Dockerfile 的 FROM 引用时再触发（基础镜像场景）	`ONBUILD COPY . /app`
`# comment`	注释行；不影响构建	`# install deps`
`# syntax=docker/dockerfile:1`	启用 Dockerfile 前端语法（BuildKit 特性）	`# syntax=docker/dockerfile:1.7`
`RUN --mount=type=cache,target=...`	BuildKit 缓存挂载，加速依赖安装	`RUN --mount=type=cache,target=/root/.m2 mvn -B package -DskipTests`
`RUN --mount=type=secret,id=...`	构建期挂载密钥，避免写入镜像层	`RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci`

多阶段构建要点

指令	说明	示例
`FROM A AS build / FROM B`	先编译再拷产物，最终镜像不含编译工具链	`FROM golang:1.22 AS build ⏎ ... ⏎ FROM gcr.io/distroless/static`
`COPY --from=build /out /app`	只复制构建产物到运行镜像	`COPY --from=build /src/app /app`
`COPY --from=image:tag /path /dest`	直接从已有镜像拷文件	`COPY --from=nginx:1.27 /etc/nginx/nginx.conf /etc/nginx/nginx.conf`

完整示例（多阶段 Java）

# syntax=docker/dockerfile:1

# ===== 构建阶段：基于 JDK 镜像 =====
FROM eclipse-temurin:17-jdk AS build
WORKDIR /src

# 安装 Maven（构建工具只存在于本阶段）
RUN apt-get update \
 && apt-get install -y --no-install-recommends maven \
 && rm -rf /var/lib/apt/lists/*

# 先只复制依赖描述，利用层缓存
COPY pom.xml .
RUN --mount=type=cache,target=/root/.m2 \
    mvn -B -q dependency:go-offline

COPY src ./src
RUN --mount=type=cache,target=/root/.m2 \
    mvn -B -DskipTests package \
 && mv target/*.jar /src/app.jar

# ===== 运行阶段：基于 JRE 镜像（体积更小）=====
FROM eclipse-temurin:17-jre
LABEL org.opencontainers.image.title="demo-api" \
      org.opencontainers.image.description="Sample Spring Boot image"

ENV JAVA_OPTS="-XX:+UseContainerSupport -XX:MaxRAMPercentage=75.0" \
    TZ=Asia/Shanghai \
    LANG=C.UTF-8

# 非 root 运行
RUN useradd -r -u 10001 app \
 && mkdir -p /app \
 && chown -R app:app /app
WORKDIR /app

COPY --from=build --chown=app:app /src/app.jar /app/app.jar

USER app
EXPOSE 8080

HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
  CMD curl -fsS http://127.0.0.1:8080/actuator/health || exit 1

ENTRYPOINT ["sh", "-c", "exec java $JAVA_OPTS -jar /app/app.jar"]
CMD []

构建：docker build -t demo-api:1.0 .　运行：docker run -d -p 8080:8080 --name demo-api demo-api:1.0

要点：构建阶段 FROM eclipse-temurin:17-jdk；运行阶段换 17-jre 减小体积；非 root + HEALTHCHECK。

文档说明

本页覆盖 Dockerfile 官方常用指令及 BuildKit 常见写法，并附多阶段构建完整示例。

1. 指令不区分大小写，习惯上全大写；一个 Dockerfile 中 CMD/ENTRYPOINT 以最后一次为准。

2. EXPOSE 只是声明，真正映射端口仍需 docker run -p 或编排配置。

3. 相关：Docker常用命令 · K8s常用命令