ONBUILD 指令已被 Docker 18.06 起弃用，它不参与当前镜像构建，仅在被用作子镜像基础时隐式触发注册指令，导致逻辑不透明、不可控、调试困难；推荐改用多阶段构建、ARG+RUN 显式参数化或公共脚本等可读可控方案。
ONBUILD 指令**不能用来简化现代 Docker 构建流程**，它已被官方弃用，且实际会增加复杂度和维护风险。
ONBUILD 的真实行为
它不参与当前镜像的构建，只在该镜像被用作 其他 Dockerfile 的 FROM 基础镜像时，才把注册的指令“自动插入”到子镜像构建过程的开头。这种隐式触发导致：
- 子镜像 Dockerfile 看不到这些操作，构建逻辑不透明
- 无法跳过、修改或加条件判断，完全失控
- 父镜像一更新 ONBUILD 内容，所有子镜像重建都会强制重跑对应步骤
- 报错时日志不显示来源，很难区分是父镜像问题还是子镜像写法问题
为什么看似“简化”，实则埋坑
比如一个标着 node:18-onbuild 的镜像，子项目只需写：
FROM node:18-onbuild EXPOSE 3000
表面看确实少写了 COPY、RUN npm install 等——但代价是：你不知道它何时执行、是否成功、能否适配你的 package-lock.json 版本，甚至不清楚它用了什么工作目录或用户权限。
真正轻量又可靠的替代方式
用显式、可读、可调试的方式达成复用目标：
-
提取公共脚本：把安装依赖、校验环境等逻辑写成
setup.sh，COPY 进镜像后RUN ./setup.sh -
用 ARG 控制行为：例如
ARG NODE_ENV=production，再通过RUN npm ci --only=$NODE_ENV实现差异化构建 -
多阶段构建复用中间产物：在 builder 阶段编译或安装，再
COPY --from=builder拷贝精简后的二进制或 node_modules - 统一模板 + CI 脚本驱动：用 Makefile 或 GitHub Actions 封装常用构建参数，避免重复写 Dockerfile
遗留项目怎么办
如果必须维护含 ONBUILD 的旧镜像，建议：
- 先用
docker history查看它到底注册了哪些触发器 - 在子镜像构建时加
--no-cache确保触发器执行（缓存可能跳过） - 尽快迁移到显式写法，不要新建任何带 ONBUILD 的镜像
清晰表达每一步意图，比依赖“自动魔法”更省心也更稳定。
