Dockerfile 核心指令详解与最佳实践指南

多阶段构建示例

通过分离构建环境与运行环境，大幅减小镜像体积。

❌ 错误示例（单阶段）： Maven 与源码永久存在镜像中，导致臃肿。

FROM openjdk:11
RUN apt-get update && apt-get install -y maven
COPY . /app
WORKDIR /app
RUN mvn package
ENTRYPOINT ["java", "-jar", "target/app.jar"]

✅ 正确示例（多阶段构建）：

# 构建阶段
FROM maven:3.9-eclipse-temurin-11 AS builder
WORKDIR /build
COPY pom.xml .
COPY src ./src
RUN mvn clean package -DskipTests

# 运行阶段
FROM openjdk:11-jre
WORKDIR /app
COPY --from=builder /build/target/app.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]

2. WORKDIR

设置工作目录。后续指令如 RUN、COPY 等默认在此目录下执行。未设置时默认为根目录 /。

FROM ubuntu:22.04
WORKDIR /usr/why/app
RUN pwd
COPY . .

相对路径会自动追加前置工作目录：

WORKDIR /app
WORKDIR why
WORKDIR test
# 最终路径为 /app/why/test

3. COPY vs ADD

COPY 是最推荐的复制指令，行为明确。ADD 功能更宽泛，支持 URL 下载和自动解压，但行为不可预测，生产环境慎用。

COPY 常用参数

• --from=<stage>：从指定构建阶段复制文件（多阶段构建核心）。
• --chown=<user>:<group>：设置文件属主（优于 RUN chown）。
• --chmod=<perms>：设置文件权限。
• --link：使用硬链接优化性能（需开启 BuildKit）。

COPY --from=builder /build/target/app.jar /app/app.jar
COPY --chown=appuser:appgroup app.jar /app/
COPY --exclude=*.md . /app/

ADD 特性

支持自动解压 .tar, .tar.gz 等格式，以及远程 URL 下载。但需注意校验完整性。

ADD --checksum=sha256:abc123 https://example.com/app.tar.gz /app/

4. ENV 与 ARG

• ENV：设置环境变量，在构建和运行时均可见。
• ARG：定义构建变量，仅在构建阶段有效，不会保留在最终镜像中。

联合使用技巧：

ARG APP_ENV=dev
ENV APP_ENV=${APP_ENV}

内置 ARG 变量：

• BUILD_DATE：构建时间。
• VCS_REF：Git 提交 hash。
• TARGETPLATFORM：当前构建平台。

5. RUN

在构建阶段执行命令并固化结果到镜像层。

Shell 格式 vs Exec 格式

• Shell 格式 (RUN echo hello)：启动 /bin/sh -c，支持管道、变量替换。
• Exec 格式 (RUN ["echo", "hello"])：直接调用程序，不经过 shell，更安全且 PID 1 可控。

最佳实践：

• 合并多条 RUN 指令以减少层数。
• 清理缓存（如 rm -rf /var/lib/apt/lists/*）在同一层完成。

RUN apt-get update \
    && apt-get install -y curl \
    && rm -rf /var/lib/apt/lists/*

BuildKit 高级选项

启用 BuildKit 后，RUN 支持更多参数：

• --mount=type=cache：挂载缓存目录（如 pip cache）。
• --mount=type=secret：安全传递密钥。
• --network=none：禁止联网，提升安全性。

RUN --mount=type=cache,target=/root/.cache pip install -r requirements.txt

6. ENTRYPOINT & CMD

• ENTRYPOINT：定义容器的固定入口程序，难以被覆盖。
• CMD：提供默认启动命令或参数，可被 docker run 覆盖。

推荐组合：

使用 Exec 格式的 ENTRYPOINT 配合 CMD 作为参数，兼顾灵活性与稳定性。

ENTRYPOINT ["nginx"]
CMD ["-g", "daemon off;"]

此时 docker run image 执行 nginx -g daemon off;，而 docker run image -t 则追加 -t 参数。

7. EXPOSE & VOLUME

• EXPOSE：声明端口，仅作为文档提示，不实际打开端口。需配合 -p 映射。
• VOLUME：声明持久化数据目录，数据独立于容器生命周期。

EXPOSE 80
VOLUME ["/data"]

8. USER & HEALTHCHECK

• USER：切换运行用户，生产环境建议不使用 root。
• HEALTHCHECK：定义健康检查命令，Docker 周期性执行判断状态。

HEALTHCHECK --interval=30s --timeout=5s CMD curl -f http://localhost:8080/health || exit 1

三、docker build 构建命令

docker build 根据 Dockerfile 生成镜像。

常用参数

• -t, --tag：指定镜像标签。
• -f, --file：指定 Dockerfile 路径。
• --build-arg：传入构建参数。
• --no-cache：禁用缓存，强制重新构建。
• --platform：指定目标架构（如 linux/amd64）。

构建上下文与 .dockerignore

构建上下文是发送给 Docker Daemon 的文件集合。务必使用 .dockerignore 排除不必要的大文件（如 .git, node_modules），否则每次构建都会上传大量无用数据。

.git
node_modules
target
dist
*.log

示例操作

# 指定 Dockerfile 构建
docker build -f Dockerfile.prod -t myapp:v1.0 .

# 传入构建参数
docker build --build-arg VERSION=1.2.3 -t myapp:latest .

# 跨平台构建
docker build --platform linux/amd64 -t myapp:amd64 .

四、SpringBoot 部署实战

以下是一个基于 Java SpringBoot 应用的完整部署流程。

1. 准备基础镜像

docker pull williamyeh/java8

2. 编写 Dockerfile

# 指定基础镜像
FROM williamyeh/java8

# 将可执行 jar 包复制到镜像
ADD api-test.jar /api-test.jar

# 暴露端口
EXPOSE 8087

# 启动命令
ENTRYPOINT ["java", "-jar", "/api-test.jar"]

3. 打包镜像

确保 api-test.jar 与 Dockerfile 在同一目录：

docker build -f Dockerfile -t why/api-test:v1.0 .

4. 启动服务

docker run -d --name api-test -p 8087:8087 why/api-test:v1.0

如需负载均衡，可在宿主机不同端口映射同一容器端口：

docker run -d --name api-test2 -p 8088:8087 why/api-test:v1.0
docker run -d --name api-test3 -p 8089:8087 why/api-test:v1.0

总结：掌握 Dockerfile 指令的核心在于理解 Layer 机制与构建上下文。生产环境中应优先使用多阶段构建、明确指定镜像版本、避免使用 root 用户，并利用 BuildKit 优化构建效率。