Dockerfile 最佳实践速查表

基础镜像 (FROM)

选择一个合适的基础镜像是编写 Dockerfile 的第一步。

``dockerfile # 使用指定版本镜像（推荐） FROM node:20-alpine

# 使用多阶段构建命名阶段 FROM golang:1.22 AS builder

# 使用精简基础镜像 FROM python:3.12-slim

# 使用 distroless 镜像（仅运行时） FROM gcr.io/distroless/base-debian12 `

构建指令 (RUN)

在镜像构建过程中执行命令。

`dockerfile # 合并多个命令减少层数 RUN apt-get update && apt-get install -y \ curl \ git \ && rm -rf /var/lib/apt/lists/*

# 使用 exec 格式（推荐） RUN ["npm", "install"]

# 设置构建时缓存 RUN --mount=type=cache,target=/root/.npm \ npm install

# 使用 HERE 文档 RUN <`

文件操作 (COPY / ADD)

将文件从构建上下文复制到镜像中。

`dockerfile # 复制文件（推荐） COPY package.json package-lock.json ./

# 复制整个目录 COPY src/ /app/src/

# 设置权限 COPY --chown=node:node config/ /app/config/

# 多阶段构建复制产物 COPY --from=builder /app/dist /usr/share/nginx/html

# ADD 自动解压 tar 包 ADD app.tar.gz /opt/app/ `

工作目录与环境变量 (WORKDIR / ENV / ARG)

`dockerfile # 设置工作目录（推荐使用绝对路径） WORKDIR /app

# 设置环境变量（运行时可用） ENV NODE_ENV=production \ PORT=3000

# 构建参数（构建时可覆盖） ARG APP_VERSION=1.0.0 ARG BUILD_DATE

# 将构建参数传递给环境变量 ENV APP_VERSION=$APP_VERSION `

暴露端口与数据卷 (EXPOSE / VOLUME)

`dockerfile # 声明容器运行时监听的端口 EXPOSE 8080 EXPOSE 443/tcp 80/udp

# 声明挂载点（匿名卷） VOLUME ["/data", "/var/log"] `

启动配置 (CMD / ENTRYPOINT)

`dockerfile # CMD 作为默认命令（可覆盖） CMD ["node", "server.js"] CMD npm start

# ENTRYPOINT 作为固定入口 ENTRYPOINT ["docker-entrypoint.sh"] ENTRYPOINT ["nginx", "-g", "daemon off;"]

# 组合使用：ENTRYPOINT + CMD ENTRYPOINT ["python"] CMD ["app.py"]

# SHELL 与 exec 格式 # exec 格式（推荐）：CMD ["executable", "param1"] # shell 格式：CMD command param1 `

用户与标签 (USER / LABEL)

`dockerfile # 创建用户并切换（安全最佳实践） RUN addgroup -S appgroup && adduser -S appuser -G appgroup USER appuser

# 设置镜像元数据 LABEL maintainer="team@example.com" LABEL version="1.0.0" LABEL description="Production web application" `

健康检查 (HEALTHCHECK)

`dockerfile # 容器健康检查 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ CMD curl -f http://localhost:8080/health || exit 1

# 禁用继承的健康检查 HEALTHCHECK NONE `

触发器与其他指令 (ONBUILD / SHELL)

`dockerfile # 触发器：当此镜像被用作基础镜像时执行 ONBUILD COPY . /app/src ONBUILD RUN make build

# 自定义 SHELL（Windows 场景） SHELL ["powershell", "-Command"] SHELL ["/bin/bash", "-c"] `

多阶段构建

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

`dockerfile # 第一阶段：编译构建 FROM golang:1.22 AS builder WORKDIR /build COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED=0 GOOS=linux go build -o app .

# 第二阶段：运行环境 FROM alpine:3.20 RUN apk add --no-cache ca-certificates tzdata COPY --from=builder /build/app /app EXPOSE 8080 USER 1001 ENTRYPOINT ["/app"]

# 利用命名阶段进行条件构建 FROM node:20-alpine AS base WORKDIR /app COPY package*.json ./

FROM base AS dev RUN npm install --only=development COPY . .

FROM base AS prod RUN npm install --only=production COPY . . `

最佳实践

`dockerfile # 1. 使用 .dockerignore 排除无关文件 # .dockerignore 内容： # node_modules # .git # *.md # Dockerfile # .env

# 2. 按变更频率排序指令（缓存利用） FROM node:20-alpine # 最不易变：包管理文件 COPY package*.json ./ RUN npm install # 最易变：源代码 COPY . .

# 3. 使用精确标签而非 latest # 错误：FROM node:latest # 正确：FROM node:20.11-alpine3.19

# 4. 最小化镜像层数 # 合并多个 RUN 指令 RUN apt-get update && \ apt-get install -y curl git && \ apt-get clean && \ rm -rf /var/lib/apt/lists/*

# 5. 不以 root 运行 RUN adduser -D myuser USER myuser

# 6. 使用 --no-install-recommends RUN apt-get install -y --no-install-recommends curl

# 7. 设置时区和语言环境 ENV TZ=Asia/Shanghai RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime ``