dockerfile-optimise

Dockerfile 优化最佳实践

完全来源于 Docker 官方文档的全面 Dockerfile 优化指南。包含 8 个类别中的 48 条规则，并按影响程度排序，以指导自动化重构和代码生成。

适用场景

在以下情况下，请参考这些指南：

• 编写新的 Dockerfile 或修改现有 Dockerfile
• 优化 Docker 构建时间（层缓存、缓存挂载、上下文管理）
• 缩小 Docker 镜像体积（多阶段构建、最小化基础镜像）
• 加强容器安全（密钥挂载、非 root 用户、证明）
• 使用 Docker 构建设置 CI/CD 管道
• 检查 Dockerfile 中的反模式

按优先级划分的规则类别

优先级	类别	影响	前缀
1	层缓存与排序	CRITICAL	cache-
2	多阶段构建	CRITICAL	stage-
3	基础镜像选择	HIGH	base-
4	构建上下文管理	HIGH	ctx-
5	安全与密钥	HIGH	sec-
6	依赖管理	MEDIUM-HIGH	dep-
7	指令模式	MEDIUM	inst-
8	质量与验证	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 - 使用目标构建区分开发版与生产版
• stage-copy-artifacts-only - 在阶段之间只复制最终产物
• stage-reusable-base - 创建可复用的基础阶段

3. 基础镜像选择（HIGH）

• base-minimal-image - 使用最小化基础镜像
• base-official-images - 使用 Docker 官方镜像
• base-pin-versions - 使用摘要固定基础镜像版本
• 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 - 使用语法指令启用最新的 BuildKit 功能（缓存挂载、密钥挂载、heredoc 和 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 和来源证明
• 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	版本和参考信息