规范的注释与排版是提升Dockerfile可维护性、协作效率和构建稳定性的关键：注释需说明“为什么”而非“做什么”，独占一行；按逻辑分区块排版，指令大写、参数小写，合理换行合并RUN，配套.dockerignore等文件同步规范。
注释和排版不是可有可无的细节，而是影响可维护性、协作效率和构建稳定性的关键习惯。规范的注释与排版能让他人（包括未来的你）快速理解构建逻辑，减少误改风险，也便于 ci/cd 流水线识别关键步骤。
注释要写得清楚、有用、不冗余
注释以 # 开头，必须独占一行或位于指令行末尾（但推荐独占行，更清晰）。重点不是“解释语法”，而是说明“为什么这么写”：
- 说明某条 RUN 的目的，比如
# 安装 curl 并清理 apt 缓存，避免镜像层残留临时文件 - 标注多阶段构建中各阶段的作用，例如
# 构建阶段：使用 golang 编译二进制文件 - 注明版本选择理由，如
# 使用 debian:slim 而非 ubuntu，减小基础镜像体积 - 避免无意义注释，比如
# COPY 文件或# 运行命令—— 指令本身已说明动作
排版要保持结构清晰、层级分明
Dockerfile 是自上而下执行的脚本，合理分段能显著提升可读性。建议按逻辑区块组织，每块之间空一行，并用注释标明意图：
- 基础信息区：FROM + LABEL（含 maintainer、version、description 等）
- 环境准备区：WORKDIR、ENV、ARG（定义构建参数）、RUN（系统更新、依赖安装）
- 代码/资源引入区：COPY（首选）或 ADD（仅当需解压或拉取 URL 时），注意按 .dockerignore 规则过滤
- 构建与清理区：RUN 编译、打包、删除中间产物（如 apt lists、缓存目录）
- 运行配置区：EXPOSE、USER、VOLUME、CMD / ENTRYPOINT
指令书写与换行要兼顾可读与正确性
所有指令（FROM、RUN、COPY 等）统一大写，参数全小写（如 FROM alpine:3.20），这是社区约定，也避免某些旧版工具兼容问题：
- 长命令用反斜杠 \ 换行，且换行符前留一个空格，每行缩进一致（推荐 2 或 4 空格）
- 多个相关 RUN 命令尽量合并，用
&&连接并结尾加&& \，防止生成冗余镜像层 - COPY 和 ADD 的源路径始终相对于 Dockerfile 所在目录，不要用绝对路径或上级目录（..）引用，否则构建会失败
- 避免在注释行里混入空格或不可见字符，有些构建器对 BOM 或全角符号敏感
配套文件也要同步规范
Dockerfile 不是孤立存在的。它和周边文件共同构成构建上下文：
- 文件名必须是 Dockerfile（首字母大写，无后缀），若要用其他名字，build 时必须显式指定
--file - 同目录下建议存在 .dockerignore，内容格式类似 .gitignore，用于排除不需要送入构建上下文的文件（如 node_modules、.git、本地配置）
- 如果用了 ARG，应在 FROM 之前声明（除非是构建参数用于选择基础镜像），并在 docker build 时用
--build-arg传入
