Dockerfile 编写片段 - 码剑客

从最小可用镜像到多阶段构建、依赖缓存、非 root 运行与体积优化的可直接复制片段。

Docker 23+ / BuildKit更新于 2026-10-29共 24 条

最小可用镜像

最小可用的 Node 运行镜像骨架

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

CMD 用 JSON 数组形式，否则会经过 shell 解析

固定小版本基础镜像，避免构建结果漂移

FROM node:20-alpine3.20

写入来源与版本元数据，便于追溯镜像

LABEL org.opencontainers.image.source="https://github.com/acme/my-app"

声明监听端口，仅作说明，不会真的映射

EXPOSE 3000

多阶段构建

Go 多阶段构建，最终镜像只保留二进制

FROM golang:1.22-alpine AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /out/app ./cmd/server

FROM gcr.io/distroless/static-debian12
COPY --from=build /out/app /app
USER nonroot:nonroot
ENTRYPOINT ["/app"]

前端构建产物交给 Nginx 托管

FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:1.25-alpine
COPY --from=build /app/dist /usr/share/nginx/html

静态二进制可放进空镜像，体积最小

FROM scratch
COPY --from=build /out/app /app
ENTRYPOINT ["/app"]

scratch 没有 shell 与证书，需要时先拷贝

分层与依赖缓存

先复制依赖清单，改业务代码时复用依赖层

COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .

用 BuildKit 缓存包管理器目录，加速重复构建

RUN --mount=type=cache,target=/root/.npm \
    npm ci --omit=dev

需要 BuildKit，Docker 23 起默认开启

.dockerignore 缩小上下文，避免密钥进镜像

node_modules
dist
.git
.env
Dockerfile

复制时直接指定属主，省掉一层 chown

COPY --chown=node:node . .

用户与运行时

创建并切换到非 root 用户运行进程

RUN addgroup -S app && adduser -S app -G app
USER app

切换前先确认工作目录对该用户可写

声明健康检查，供编排组件判断存活

HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
    CMD wget -qO- http://127.0.0.1:3000/health || exit 1

精简镜像可能没有 curl，可用 wget 或自带脚本

固定入口脚本，默认参数可被运行时覆盖

ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["--config", "/etc/app/config.yaml"]

exec 形式下两者拼接成完整命令；shell 形式会忽略 CMD

声明停止信号，配合应用优雅退出

STOPSIGNAL SIGTERM

构建参数与目标阶段

传入构建期变量，不要用它传递密钥

docker build --build-arg NODE_ENV=production -t my-app:1.0 .

ARG 值会留在镜像历史里，docker history 可见

只构建到指定阶段，便于调试中间产物

docker build --target build -t my-app:builder .

为指定架构构建镜像，适配服务器 CPU

docker build --platform linux/amd64 -t my-app:1.0 .

跨架构构建依赖 buildx，本机构建可能很慢

忽略全部缓存重建，排查陈旧层问题

docker build --no-cache -t my-app:1.0 .

指定 Dockerfile 路径，末位参数仍是上下文

docker build -f docker/Dockerfile.prod -t my-app:1.0 .

减小镜像体积

安装后清理 apt 缓存，同一层内完成

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

只装生产依赖并清理 npm 缓存

RUN npm ci --omit=dev && npm cache clean --force

优先选 alpine 或 slim 作为基础镜像

FROM node:20-slim

Alpine 用 --no-cache，免去手动清理索引

RUN apk add --no-cache curl