build-args 作用详解

什么是 build-arg

Docker build 的 --build-arg 参数允许在构建镜像时动态传入变量，在 Dockerfile 中通过 ARG 指令接收。

基本用法

docker build \
  --build-arg VERSION=1.0.0 \
  --build-arg NODE_ENV=production \
  -t myapp:1.0.0 .

FROM node:18

# 声明构建参数
ARG VERSION
ARG NODE_ENV=development  # 可以设默认值

# 使用构建参数
WORKDIR /app
COPY . .

RUN if [ "$NODE_ENV" = "production" ]; then \
      npm ci --only=production; \
    else \
      npm install; \
    fi

LABEL version=$VERSION

典型使用场景

1. 环境区分

FROM node:18 AS builder
ARG BUILD_ENV

COPY . /app
WORKDIR /app

RUN if [ "$BUILD_ENV" = "production" ]; then \
      npm run build:prod; \
    else \
      npm run build:dev; \
    fi

# 开发构建
docker build --build-arg BUILD_ENV=development -t myapp:dev .

# 生产构建
docker build --build-arg BUILD_ENV=production -t myapp:prod .

2. 软件源配置

FROM ubuntu:22.04

ARG APT_MIRROR="archive.ubuntu.com"

RUN sed -i "s/archive.ubuntu.com/$APT_MIRROR/g" /etc/apt/sources.list && \
    apt-get update && \
    apt-get install -y nginx

# 国内用户使用阿里云镜像加速
docker build --build-arg APT_MIRROR=mirrors.aliyun.com -t myapp .

3. 代理设置

FROM node:18

ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

RUN npm config set proxy $HTTP_PROXY && \
    npm install

docker build \
  --build-arg HTTP_PROXY=http://proxy.company.com:8080 \
  --build-arg HTTPS_PROXY=http://proxy.company.com:8080 \
  -t myapp .

4. 版本控制

FROM golang:1.21 AS builder

ARG APP_VERSION
ARG GIT_COMMIT
ARG BUILD_TIME

WORKDIR /app
COPY . .

RUN go build \
  -ldflags="-X main.Version=$APP_VERSION \
            -X main.GitCommit=$GIT_COMMIT \
            -X main.BuildTime=$BUILD_TIME" \
  -o /app/server .

ARG 与 ENV 的区别

特性	ARG	ENV
作用域	仅构建阶段	构建阶段 + 容器运行时
继承	不会传递给子镜像	会传递给子镜像
持久化	仅构建过程	容器运行时也能访问
持久命名	可作为 ENV 的默认值	可作为容器进程环境变量

FROM ubuntu:22.04

ARG MY_ARG=default_value
ENV MY_ENV=$MY_ARG  # 可以把 ARG 赋给 ENV

安全注意事项

重要：不要在 build-arg 中传递密码或密钥！

# ❌ 危险！build-arg 会在构建历史中泄露
ARG DB_PASSWORD
ENV DB_PASSWORD=$DB_PASSWORD

# 构建历史中会存储密码
docker history myapp:latest

正确做法：使用 Docker secrets 或 BuildKit 的 secret mount：

# syntax=docker/dockerfile:1
FROM node:18

# ✅ 安全的方式
RUN --mount=type=secret,id=npmrc \
    cp /run/secrets/npmrc ~/.npmrc && \
    npm install

DOCKER_BUILDKIT=1 docker build \
  --secret id=npmrc,src=.npmrc \
  -t myapp .

面试要点

build-arg 是构建时变量，不会保留在最终镜像中（除非通过 ENV 赋值）
典型用途：环境区分、源替换、代理、版本信息注入
不能用于传递敏感信息——会泄露在构建历史中
ARG 和 ENV 的区别是高频面试题
BuildKit 的 --secret 是安全的替代方案

面试官常问：你在项目里怎么使用 build-arg 的？为什么要区分 ARG 和 ENV？

文章版权归作者所有，未经允许请勿转载。

THE END

Agent 智能体开发

build-args 作用详解

build-args 作用详解

什么是 build-arg

基本用法

典型使用场景

1. 环境区分

2. 软件源配置

3. 代理设置

4. 版本控制

ARG 与 ENV 的区别

安全注意事项

面试要点

请登录后发表评论