docker构建参数需通过arg声明并用--build-arg传入，带默认值更安全；多阶段需重复声明；敏感信息禁用arg；构建时转env才能运行时使用。
直接在构建命令里加 --build-arg，配合 Dockerfile 中的 ARG 声明，就能让一个镜像适配开发、测试、生产等不同环境。关键不是“能不能传”，而是“怎么传得准、用得稳、不踩坑”。
在 Dockerfile 中正确定义 ARG 参数
ARG 必须显式声明，才能被构建过程识别。声明位置灵活，但带默认值的写法更安全：
- 写成
ARG ENVIRONMENT=dev，不传参时自动用dev - 写成
ARG API_URL（无默认值），若构建时不传就会报错 - 多个参数可分行写，顺序无关，例如：
ARG APP_VERSION<br>ARG COMMIT_SHA<br>ARG BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ)
注意：命令替换需在 RUN 中执行，ARG 行本身不支持执行 shell
构建时传参的三种可靠方式
避免手动敲长命令出错，也方便 CI/CD 集成：
OpenClaw Docker Setup
下载
在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...
- 命令行单次传入：
docker build --build-arg ENVIRONMENT=prod --build-arg APP_VERSION=2.4.1 -t myapp:prod . - 从文件加载（适合参数多或含空格/特殊字符）：
新建.buildargs文件，内容如：ENVIRONMENT=staging<br>API_URL=https://staging.api.com<br>FEATURE_FLAG=true
然后运行：docker build $(cat .buildargs | xargs -I {} echo "--build-arg {}") -t myapp:staging . - CI/CD 中透传变量：
GitHub Actions 示例：--build-arg COMMIT_SHA=${{ github.sha }} --build-arg ENVIRONMENT=${{ env.ENV }}
GitLab CI 示例：--build-arg CI_COMMIT_TAG=$CI_COMMIT_TAG
让构建参数在容器运行时也能用
ARG 只存在于构建阶段，如果应用启动时需要读取这些值（比如前端配置、日志级别），必须显式转成 ENV：
- 在 Dockerfile 中加一句：
ENV APP_ENV=$ENVIRONMENT
这样$APP_ENV就能在容器里通过printenv APP_ENV看到 - 也可以组合使用：
ARG NODE_ENV=production<br>ENV NODE_ENV=$NODE_ENV<br>RUN npm ci --only=production
既控制构建行为，又为运行时提供环境标识 - 注意：不要写成
ENV NODE_ENV=${NODE_ENV:-development}—— 这种语法在 ENV 中不生效，${} 展开只在 RUN 中可用
避开高频陷阱
很多问题其实就卡在几个细节上：
-
FROM 前后作用域隔离：只有在
FROM指令之前声明的 ARG，才能用于指定基础镜像名，例如：ARG BASE_IMAGE=alpine:3.19<br>FROM $BASE_IMAGE
-
多阶段构建需重复声明：每个
FROM开启新阶段，ARG 不自动继承，必须在每个阶段开头重新写ARG XXX -
敏感信息别走 ARG：密码、token、密钥等不能用 --build-arg 传，因为可能残留于镜像历史层（
docker history可查）。应改用docker buildx build --secret或挂载文件方式 -
大小写与空格要小心：KEY 推荐全大写；VALUE 含空格或特殊字符时必须用单引号包裹，例如：
--build-arg CONFIG='{"timeout":30,"retry":2}'
