用途
Dockerfile 优化最佳实践（Dockerfile Optimization Best Practices）。该技能是一份全面的 Dockerfile 优化指南，内容完全取自 Docker 官方文档，包含 48 条规则，分布在 8 个类别中，并按影响程度排序，用于指导自动重构和代码生成。
适用时机
在以下情况可参考这些指南：
- 编写新的 Dockerfile 或修改现有 Dockerfile
- 优化 Docker 构建时间（层缓存、缓存挂载、上下文管理）
- 减小 Docker 镜像大小（多阶段构建、最小化基础镜像）
- 强化容器安全（密钥挂载、非 root 用户、证明）
- 搭建带 Docker 构建的 CI/CD 流水线
- 审查 Dockerfile 中的反模式
规则类别与优先级
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | Layer Caching & Ordering | CRITICAL | cache- |
| 2 | Multi-Stage Builds | CRITICAL | stage- |
| 3 | Base Image Selection | HIGH | base- |
| 4 | Build Context Management | HIGH | ctx- |
| 5 | Security & Secrets | HIGH | sec- |
| 6 | Dependency Management | MEDIUM-HIGH | dep- |
| 7 | Instruction Patterns | MEDIUM | inst- |
| 8 | Quality & Validation | MEDIUM | lint- |
1. 层缓存与顺序（CRITICAL）
- cache-layer-order — 按变更频率排列层
- cache-copy-deps-first — 在源代码之前复制依赖文件
- cache-copy-link — 使用 COPY --link 进行高效的缓存层复制
- cache-mount-package — 为包管理器使用缓存挂载
- cache-apt-combine — 将 apt-get update 与 install 合并
- cache-external — 在 CI/CD 构建中使用外部缓存
- cache-invalidation — 避免不必要的缓存失效
- cache-minimize-layers — 合并相关的 RUN 指令
2. 多阶段构建（CRITICAL）
- stage-separate-build-runtime — 分离构建阶段与运行阶段
- stage-named-stages — 使用命名的构建阶段
- stage-parallel-branches — 利用阶段的并行执行
- stage-target-builds — 使用 target 构建区分开发/生产
- stage-copy-artifacts-only — 仅在阶段之间复制最终产物
- stage-reusable-base — 创建可复用的基础阶段
3. 基础镜像选择（HIGH）
- base-minimal-image — 使用最小化基础镜像
- base-official-images — 使用 Docker 官方镜像
- base-pin-versions — 使用摘要（digest）固定基础镜像版本
- base-arg-version — 在 FROM 之前使用 ARG 参数化基础镜像
- base-rebuild-regularly — 定期使用 --pull 重新构建镜像
- base-distroless — 生产环境使用 distroless 或 scratch 镜像
4. 构建上下文管理（HIGH）
- ctx-dockerignore — 使用 .dockerignore 排除不必要的文件
- ctx-bind-mounts — 对仅构建期使用的文件使用绑定挂载而非 COPY
- ctx-minimize-context — 保持构建上下文尽可能小
- ctx-syntax-directive — 使用 syntax 指令以启用最新 BuildKit 特性（缓存挂载、密钥挂载、heredocs、COPY --link 的前提条件）
5. 安全与密钥（HIGH）
- sec-secret-mounts — 对敏感数据使用密钥挂载
- sec-non-root-user — 以非 root 用户运行
- sec-no-secrets-in-args — 绝不通过 ARG 或 ENV 传递密钥
- sec-ssh-mounts — 访问私有仓库时使用 SSH 挂载
- sec-attestations — 启用 SBOM 与来源（provenance）证明
- sec-no-unnecessary-packages — 避免安装不必要的软件包
- sec-ephemeral-containers — 设计临时、无状态的容器
6. 依赖管理（MEDIUM-HIGH）
- dep-cache-mount-apt — 为 apt 包管理器使用缓存挂载
- dep-cache-mount-npm — 为 npm、yarn 和 pnpm 使用缓存挂载
- dep-cache-mount-pip — 为 pip 使用缓存挂载
- dep-version-pin — 固定软件包版本以保证可复现性
- dep-cleanup-caches — 在同一层中清理包管理器缓存
7. 指令模式（MEDIUM）
- inst-json-cmd — CMD 与 ENTRYPOINT 使用 JSON 形式
- inst-healthcheck — 为容器编排定义 HEALTHCHECK
- inst-heredoc-scripts — 使用 heredoc 编写多行脚本
- inst-entrypoint-exec — 在入口脚本中使用 exec
- inst-workdir-absolute — WORKDIR 使用绝对路径
- inst-copy-over-add — 优先使用 COPY 而非 ADD
8. 质量与校验（MEDIUM）
- lint-build-checks — 启用 Docker 构建检查
- lint-pipefail — 对管道连接的 RUN 命令使用 pipefail
- lint-labels — 使用标准标签记录镜像元数据
- lint-sort-arguments — 多行参数按字母顺序排序
- lint-single-concern — 每个容器只负责一件事
使用方式
阅读各个参考文件以获取详细说明和代码示例：
- 章节定义 — 类别结构与影响级别
- 规则模板 — 添加新规则的模板
参考文件：
| 文件 | 说明 |
|---|---|
| references/_sections.md | 类别定义与顺序 |
| assets/templates/_template.md | 新规则模板 |
| metadata.json | 版本与参考信息 |