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
• 一次定义，多处复用，表面看确实像“模板”

为什么不能真当模板用？

隐式行为破坏构建确定性，实际落地时问题远多于便利：

Docker Image Puller

使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。

下载

• 子镜像构建日志里看不到 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 查看 OnBuild 字段，确认注册了哪些触发器
• 构建子镜像时加 --no-cache 并观察完整日志，确认触发顺序和执行结果
• 优先考虑逐步迁移：保留原基础镜像 tag，新建一个不含 ONBUILD 的版本（如 :v2），引导团队切换