dockerfile-best

Dockerfile Best Practices Skill — 镜像构建实战

何时使用

• 写新 Dockerfile / 优化现有镜像
• 镜像太大（> 1GB）需要瘦身
• 排查 layer 缓存命中率低 / 构建慢
• 容器以 root 跑 / 信号收不到 / 僵尸进程
• CI 集成 SBOM / CVE 扫描 / 镜像签名

一、十条铁律

1. Multi-stage build — build 阶段与运行阶段分离
2. 最小 base image — distroless / scratch / alpine（按需）
3. non-root user — 永不以 root 运行
4. .dockerignore — 比 .gitignore 更严格
5. 指令排序按变化频率 — 不变的在前，常变的在后（layer 缓存）
6. 复制依赖清单先于源码 — package.json 先 COPY + install，再 COPY .
7. COPY 不用 ADD（除非要解压 / URL）
8. 明确 EXPOSE / HEALTHCHECK — 不依赖默认
9. exec form CMD —CMD ["node","app.js"] 而非 CMD node app.js
10. pin 版本 — node:20.11.1-alpine3.19 而非 node:latest

二、Multi-stage 标准模板（Node.js）

# ================ Stage 1: deps ================
FROM node:20.11.1-alpine AS deps
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile --prod=false

# ================ Stage 2: build ================
FROM node:20.11.1-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN corepack enable && pnpm build && pnpm prune --prod

# ================ Stage 3: runner ================
FROM node:20.11.1-alpine AS runner
WORKDIR /app

# non-root
RUN addgroup -S app && adduser -S app -G app
USER app

# 仅拷贝运行时所需
COPY --from=builder --chown=app:app /app/node_modules ./node_modules
COPY --from=builder --chown=app:app /app/dist ./dist
COPY --from=builder --chown=app:app /app/package.json ./

ENV NODE_ENV=production
ENV PORT=8080
EXPOSE 8080

HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD wget --quiet --spider http://localhost:8080/healthz || exit 1

CMD ["node", "dist/server.js"]

三、Go 应用（极致小）

# ================ build ================
FROM golang:1.22-alpine AS build
WORKDIR /src

# 缓存 modules（独立 layer）
COPY go.mod go.sum ./
RUN go mod download

COPY . .
# 静态链接 + strip
RUN CGO_ENABLED=0 GOOS=linux go build \
    -ldflags="-s -w" \
    -trimpath \
    -o /out/app ./cmd/server

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