ONBUILD指令自Docker 18.06起已被弃用，因其隐式执行、调试困难、缓存失效严重且不向下传递；推荐改用显式脚本、ARG+RUN参数化或多阶段构建替代。
ONBUILD 指令曾被用于实现项目模板化——即在基础镜像中预设构建逻辑，让下游子镜像“自动继承”通用步骤，减少重复编写 Dockerfile。但该方式现已弃用，不应用于新项目。Docker 自 18.06 版本起将其标记为 deprecated，官方明确建议停止使用。
ONBUILD 的模板化原理（仅作理解）
它本质是“延迟注册触发器”：在父镜像 Dockerfile 中写 ONBUILD COPY package.json /app/，构建出的镜像本身不执行这步；但当另一个 Dockerfile 以它为 FROM 时，该指令会自动插入到子镜像构建流程的 FROM 之后、其余指令之前执行。
- 适合封装固定动作，比如统一复制依赖文件、安装生产依赖、设置工作目录
- 子镜像 Dockerfile 可极简，例如只写
FROM my-node-base:onbuild和CMD - 一次定义，多处复用，表面看确实像“模板”
为什么不能真当模板用？
隐式行为破坏构建确定性，实际落地时问题远多于便利：
- 子镜像构建日志里看不到 ONBUILD 指令来源，报错时无法快速定位是父镜像逻辑还是子镜像上下文导致
- 无法跳过、重试或参数化某条 ONBUILD 步骤，比如想跳过
npm ci改用npm install --no-save就做不到 - 父镜像更新 ONBUILD 内容后，所有子镜像重建都会强制刷新对应层，缓存失效严重
- ONBUILD 不向下传递——B 镜像基于 A 构建并触发了 ONBUILD，C 镜像再基于 B 构建时，A 的 ONBUILD 不再生效，模板链断裂
现代模板化替代方案
用显式、可控、可调试的方式达成同样目标：
-
提取公共脚本：把初始化逻辑（如依赖安装、目录准备）写成
setup.sh，COPY 进基础镜像，子镜像中显式RUN ./setup.sh -
ARG + RUN 组合：用
ARG NODE_ENV=production定义变量，配合RUN npm ci --only=$NODE_ENV实现条件行为 - 多阶段构建复用：在 builder 阶段完成编译/安装，运行阶段只 COPY 必需产物，既减小体积又避免重复操作
-
Makefile 或 CI 模板：将镜像构建逻辑抽离到 Makefile（如
make build-node-app APP_DIR=./api），统一管理路径、标签、参数
遗留项目维护提示
若必须阅读或修改含 ONBUILD 的旧镜像：
- 用
docker inspect <image></image>查看OnBuild字段，确认注册了哪些触发器 - 构建子镜像时加
--no-cache并观察完整日志，确认触发顺序和执行结果 - 优先考虑逐步迁移：保留原基础镜像 tag，新建一个不含 ONBUILD 的版本（如
:v2），引导团队切换
