核心是先声明再使用、按阶段管理作用域：arg必须前置声明才生效，未声明即引用会为空或报错；支持默认值（不传参仍可构建）和无默认值（必须--build-arg显式传入）；声明位置决定作用域（from前仅影响镜像标签，from后仅限当前阶段）；多阶段需各阶段重复声明；--build-arg参数名须完全匹配（大小写敏感），可用run echo验证注入，需运行时可用则转为env。

用 ARG 实现构建期参数传递，核心就一条：先声明、再使用、按阶段管好作用域。

ARG 必须提前声明才能生效

在 Dockerfile 里，ARG 指令得写在它被引用的指令之前。没声明就直接写 ${MY_VAR}，结果一定是空或者报错（Docker 18.09+ 会直接拒绝构建）。

• 带默认值： ARG APP_VERSION=1.0.0 —— 构建时不传也能跑
• 无默认值： ARG API_TOKEN —— 必须用 --build-arg 显式传入，否则变量为空字符串
• 声明位置影响可用范围：放在第一个 FROM 前面的 ARG，只能用于该 FROM 的镜像标签；放在某个 FROM 后面的 ARG，只对当前构建阶段有效

构建时用 --build-arg 精准传参

docker build 命令通过 --build-arg 把值送进 Dockerfile，参数名必须和 ARG 声明完全一致（大小写敏感），拼错也不会报错，只是变量不生效。

OpenClaw Docker Setup

在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...

下载

• 基本用法：docker build --build-arg APP_VERSION=2.4.1 -t myapp .
• 多个参数可重复加：--build-arg MODE=prod --build-arg DEBUG=false
• 值含空格或特殊字符时，建议加引号：--build-arg REPO_URL="https://my.repo/path with space"

多阶段构建要各阶段单独声明

每个构建阶段作用域隔离，前一阶段的 ARG 不会自动延续到下一阶段。想在 builder 和 runtime 阶段都用 NODE_VERSION，就得各自写一遍 ARG。

• 正确写法：
• ARG NODE_VERSION=18
• FROM node:${NODE_VERSION} AS builder
• ARG NODE_VERSION ← 第二阶段开头必须重申
• FROM ubuntu:22.04
• RUN echo "Using ${NODE_VERSION}"

验证是否传成功，加一句 RUN echo 最直接

构建过程里插个临时输出，是最快判断参数有没有注入的方式。

• 比如加一行：RUN echo "Build version: ${APP_VERSION}"
• 如果日志里显示 Build version: 后面空着，说明没传、传错名，或作用域不对
• 需要运行时也用这个值？用 ENV 接住：ENV APP_VERSION=${APP_VERSION}，这样 CMD 或容器内程序就能读到了