ONBUILD指令的核心价值是预埋构建逻辑以统一微服务构建流程，仅适用于构建期共性动作如创建目录、安装依赖、写入元数据等，不适用于运行时配置；其禁用嵌套、需显式声明依赖，并推荐用LABEL/ARG增强可追溯性；官方已将其标记为legacy，建议新项目采用多阶段构建等现代替代方案。
ONBUILD 指令的核心价值，是在基础镜像中“预埋”构建逻辑，让下游服务镜像在继承时自动执行标准化动作，从而统一企业内微服务的构建流程。它不是用来定制当前镜像的，而是为别人定制你而准备的——这正是企业级基础镜像复用与治理的关键支点。
明确 ONBUILD 的适用边界：只做“构建期共性动作”
ONBUILD 不适合处理运行时配置、启动逻辑或环境变量注入等容器启动阶段行为。它只应在构建子镜像时触发，且必须是所有下游服务都需一致执行的操作。常见合规场景包括：
- 自动创建标准应用目录结构（如 /app/src、/app/config）
- 强制校验并复制 package.json 或 pom.xml 后执行依赖安装（RUN npm install 或 RUN mvn clean package -DskipTests）
- 写入构建元数据（如 Git commit hash、CI 构建时间），通过 ENV BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ) 配合 RUN 实现
- 复制企业内部通用构建脚本（如 COPY build-scripts/ /usr/local/bin/）并设为可执行
避免 ONBUILD 嵌套与隐式依赖
ONBUILD 指令不会跨层级传递。如果镜像 A 定义了 ONBUILD，镜像 B 以 A 为 FROM 并构建成功，那么镜像 C 以 B 为 FROM 时，A 中定义的 ONBUILD 不会再次触发。这意味着：
- 不要依赖多层 ONBUILD 级联执行，企业基础镜像应尽量扁平化，建议仅由一级官方镜像（如 openjdk:17-jre-slim、node:20-alpine）直接派生
- 若需组合多个构建步骤，应将它们合并到单条 ONBUILD 中，或改用显式 COPY + RUN 组合，避免语义模糊
- 禁止在 ONBUILD 中调用未声明的工具（如 RUN yarn install 而基础镜像未预装 yarn），所有依赖必须在基础镜像构建阶段就已就绪
用 LABEL + ARG 增强可追溯性与可控性
单独使用 ONBUILD 容易导致构建行为不可见、不可配置。推荐搭配以下实践提升企业治理能力：
- 在基础镜像中通过 LABEL org.opencontainers.image.source=https://git.example.com/base-images/java17 注明源仓库，便于审计
- 对关键 ONBUILD 行为添加 LABEL 标识，例如 LABEL onbuild.action="npm-install" onbuild.path="/app"
- 用 ARG 声明可选参数（如 ARG NODE_ENV=production），并在 ONBUILD RUN 中引用，使下游可通过 --build-arg 覆盖
- 在 ONBUILD 前加注释说明用途和预期输入，例如 # ONBUILD: expect ./package.json in build context, will run npm ci --only=production
替代方案评估：ONBUILD 正在被更现代的方式取代
Docker 官方自 2020 年起已将 ONBUILD 标记为“legacy”，不鼓励新项目使用。企业升级路径应逐步转向：
- 多阶段构建（Multi-stage）：将构建环境与运行环境分离，在 builder 阶段完成编译/安装，再 COPY 成果到 lean runtime 镜像，更安全、更可控
- 构建参数化模板（如 docker buildx bake）：用 docker-compose.build.yml 或 docker-bake.hcl 统一管理不同服务的构建逻辑，支持变量注入、条件分支
- 共享构建脚本 + 标准化 Dockerfile 头部：在 CI 流程中统一执行 ./scripts/setup-env.sh，再运行标准 Dockerfile，把“构建契约”从镜像层移到流程层
对于存量系统，ONBUILD 仍可稳定使用；新建基础镜像建议优先采用多阶段构建 + 公共构建阶段复用模式。
