Docker Desktop 本身不提供图形化界面设置 --build-arg，需在终端中执行 docker build --build-arg 命令；ARG 必须在 FROM 前声明且各阶段独立声明，不可用于 COPY 源路径或 FROM 镜像标签（除非已前置声明），敏感信息禁用 --build-arg 以防泄露。
docker build --build-arg 怎么在 Docker Desktop 里用
Docker Desktop 本身不提供图形化界面来填 --build-arg，它只是运行 docker build 命令的宿主环境。你依然得在终端（PowerShell、CMD、Git Bash 或 VS Code 终端）里执行带 --build-arg 的命令——Docker Desktop 启动后，这些命令就正常生效。
常见错误是以为要进 Docker Desktop 设置里找“构建参数”开关，其实没有这个入口。只要 docker CLI 可用（docker version 能返回信息），--build-arg 就能用。
- 确保 Docker Desktop 已启动且状态栏图标为绿色（Windows/macOS）
- 打开任意终端，cd 到含
Dockerfile的目录 - 直接运行：
docker build --build-arg APP_ENV=staging --build-arg VERSION=2.3.1 -t myapp . - 若用 Windows PowerShell，变量值含空格或特殊字符时，建议用双引号包裹：
--build-arg "BUILD_FLAGS=--no-cache"
ARG 在 Dockerfile 里怎么声明才不会报错
ARG 必须出现在 FROM 指令之前，或至少在它被首次引用的阶段开头；否则构建会失败，提示 ARG before FROM is not supported 或变量为空字符串。
多阶段构建中，每个阶段都要单独声明 ARG，不能跨阶段继承：
ARG BUILD_ENV=production FROM node:18 AS builder ARG BUILD_ENV # 必须重声明，即使同名 RUN echo "Building for $BUILD_ENV" <p>FROM alpine:latest ARG BUILD_ENV # 运行阶段也要再声明 ENV NODE_ENV=$BUILD_ENV COPY --from=builder /app/dist /app</p>
- 始终给
ARG设默认值（如ARG NODE_ENV=development），避免漏传导致构建中断 -
ARG名称区分大小写，--build-arg app_env=value不会赋值给ARG APP_ENV - 不要在
FROM行里直接用未声明的ARG，例如FROM nginx:${VERSION}前必须有ARG VERSION
为什么 docker build 传了 --build-arg，RUN 里却读不到
最常见原因是变量作用域错位：你在某个构建阶段声明了 ARG，但尝试在另一个阶段或指令上下文（比如 COPY 的源路径）里引用它——ARG 只对后续的 RUN、ENV、WORKDIR 等指令生效，不参与文件路径解析或镜像拉取逻辑。
-
COPY ./src-$APP_VERSION/ /app/❌ 不合法：ARG不能用于COPY源路径 -
FROM alpine:${ALPINE_VERSION}✅ 合法，但前提是ARG ALPINE_VERSION出现在FROM之前 -
RUN echo $APP_VERSION✅ 正常输出，前提是该RUN在ARG APP_VERSION声明之后 - 如果用了 shell 形式
RUN ["sh", "-c", "echo $APP_VERSION"]，变量不会展开（因为 exec 形式不走 shell），应改用 shell 形式：RUN echo $APP_VERSION
敏感信息能不能用 --build-arg 传
不能。虽然 ARG 值不会固化进最终镜像的元数据，但如果在 RUN 中用它拼接命令（比如 curl -H "Authorization: Bearer $TOKEN"），该命令会被记录在镜像某一层的 history 里，用 docker history --no-trunc 就能看到完整命令行，密钥就泄露了。
- 正确做法：构建时不依赖敏感信息，运行时通过
docker run -e TOKEN=xxx或--env-file注入 - CI/CD 场景下，用 secret 管理工具（GitHub Actions secrets、GitLab CI variables）配合
--build-arg仅传非敏感标识（如BUILD_ID），而非密钥本身 - 若必须在构建时验证权限（如私有 npm registry），改用
RUN --mount=type=secret挂载临时凭证文件，不走环境变量
真正容易被忽略的是：ARG 和 ENV 的混合使用。比如 ARG API_KEY + ENV API_KEY=${API_KEY}，这等于把构建时传入的密钥写进了镜像配置，docker inspect 一眼可见——这种写法比裸用 --build-arg 更危险。
