ARG 构建参数

ARG 指令允许在构建时传入变量，实现动态构建。

基本用法

dockerfile

# 声明构建参数（带默认值）
ARG NODE_ENV=production
ARG VERSION=1.0

# 使用参数
FROM node:18-${VERSION}
ENV NODE_ENV=$NODE_ENV

RUN echo "Building for $NODE_ENV"

Bash

# 构建时传入参数
docker build --build-arg NODE_ENV=development --build-arg VERSION=20 -t my-app .

ARG vs ENV

dockerfile

# ARG 仅构建时可用
ARG BUILD_VERSION
RUN echo "Build version: $BUILD_VERSION"

# ENV 构建和运行时均可用
ENV APP_VERSION=1.0
CMD ["echo", "App version: $APP_VERSION"]

对比项	ARG	ENV
作用域	构建阶段	构建和运行时
容器内访问	❌	✅
传入方式	`--build-arg`	`-e` 或 Dockerfile
用途	构建配置	运行时配置

实用场景

动态基础镜像

dockerfile

ARG PYTHON_VERSION=3.11
FROM python:${PYTHON_VERSION}-slim

ARG NODE_VERSION=18
FROM node:${NODE_VERSION}-alpine

Bash

# 构建不同版本
docker build --build-arg PYTHON_VERSION=3.12 -t my-app:py312 .
docker build --build-arg NODE_VERSION=20 -t my-app:node20 .

代理设置

dockerfile

ARG HTTP_PROXY
ARG HTTPS_PROXY

ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

RUN apt-get update && apt-get install -y curl

Bash

# 构建时使用代理
docker build --build-arg HTTP_PROXY=http://proxy:8080 -t my-app .

构建版本注入

dockerfile

ARG GIT_COMMIT
ARG BUILD_DATE

LABEL git-commit=$GIT_COMMIT
LABEL build-date=$BUILD_DATE

RUN echo "Built from $GIT_COMMIT on $BUILD_DATE"

Bash

# 注入 Git 信息
docker build \
  --build-arg GIT_COMMIT=$(git rev-parse --short HEAD) \
  --build-arg BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  -t my-app .

作用域规则

dockerfile

# ARG 在声明前不可用
RUN echo $VERSION  # 空值

ARG VERSION=1.0
RUN echo $VERSION  # 1.0

# ARG 在 FROM 之后作用域重置
ARG VERSION=1.0
FROM ubuntu:22.04
RUN echo $VERSION  # 空值（FROM 后作用域重置）

# 需要在 FROM 后重新声明
ARG VERSION=1.0
FROM ubuntu:22.04
ARG VERSION
RUN echo $VERSION  # 1.0

安全注意

dockerfile

# 不要在 ARG 中存储敏感信息
ARG SECRET_KEY=123456  # 不安全！构建历史可见

# 查看构建历史
docker history my-app
# 会暴露 ARG 值

ARG 值会出现在镜像历史和构建日志中，不要传入密码、密钥等敏感信息。

要点总结

ARG 仅在构建时可用，ENV 在构建和运行时均可用
使用 --build-arg 在构建时传入参数
可用于动态基础镜像、代理设置、版本注入
ARG 在 FROM 后作用域重置，需重新声明
ARG 值暴露在构建历史中，不要传入敏感信息

📝 发现内容有误？点击此处直接编辑