ONBUILD 的作用
ONBUILD 把一条指令登记为触发器，在下游镜像 FROM 本镜像时自动执行。它适合做基础镜像：把统一的构建步骤（复制源码、安装依赖、执行构建）注入给所有下游项目，避免每个项目重复书写同样的片段。代价是下游构建时会执行「看不见的指令」，报错现场出现在下游项目里，根因却可能在基础镜像。
基本信息
| 用途 | 为基础镜像预置下游构建步骤 |
|---|---|
| 语法 | ONBUILD 后接任意构建指令 |
| 查看方式 | docker inspect -f '{{.Config.OnBuild}}' 镜像 |
| 执行时机 | 下游 FROM 本镜像之后、下游自身指令之前 |
| 限制 | ONBUILD 不能触发另一个 ONBUILD |
典型使用场景
- 公司统一基础镜像，下游只写少量业务指令
- 语言运行时基础镜像预置依赖安装步骤
- 统一构建规范，避免各项目写法不一致
- 把框架脚手架注入下游项目
- 排查下游构建的神秘失败：先检查基础镜像的触发器
基础镜像中的触发器
基础镜像中的触发器
# 基础镜像
FROM alpine:3.20
WORKDIR /app
ONBUILD COPY app/ /app/
ONBUILD RUN npm ci --prefix /app
CMD ["node", "/app/index.js"]查看与验证
查看与验证
docker inspect -f '{{.Config.OnBuild}}' registry.example.com/base/node:20 # 查看触发器
docker build -t app/web:1.0 . # 下游构建时会自动执行触发器中的步骤
docker history app/web:1.0 | head # 从构建历史反查执行了哪些指令特性与注意点
| 方面 | 说明 | 注意 |
|---|---|---|
| 执行时机 | 下游 FROM 之后、下游指令之前 | 顺序可能与下游预期不一致 |
| 作用范围 | 仅对直接下游生效一次 | 不会继承到更下游 |
| 查看方式 | inspect 的 Config.OnBuild | 排查时先看这里 |
| 调试难度 | 报错在下游，根因在基础镜像 | 需要同时看两侧 |
触发器里的 COPY 路径是相对下游项目上下文解析的，基础镜像里写死路径等于要求下游按约定放置目录，这个约定要写进文档。
ONBUILD 不能触发另一个 ONBUILD：多层基础镜像的链路不会把触发器继续往下传。