Docker ARG 指令深度解析：2026 年云原生构建实践指南

2026-02-14 01:09:50 0条评论 1次阅读 0人点赞

在 Docker 的世界里，如何编写一个既灵活又复用性高的 Dockerfile 往往是构建高质量镜像的关键。你是否遇到过这样的情况：同一个应用需要在不同环境（开发、测试、生产）中构建，仅仅是因为某些配置参数不同，就要维护多个几乎一模一样的 Dockerfile？这不仅繁琐，而且容易出错。别担心，Docker ARG 指令正是为了解决这一问题而生的。

在这篇文章中，我们将深入探讨如何在 Dockerfile 中有效地使用 ARG 指令，了解它与 ENV 指令的本质区别，并结合 2026 年最新的云原生开发理念，展示如何利用它来实现镜像的参数化构建。无论你是初学者还是有一定经验的开发者，这篇文章都将帮助你编写更优雅、更高效的 Dockerfile。

1 重新认识构建时变量：ARG 指令基础
2 ARG 与 ENV 的本质区别：深入理解
3 实战指南：如何在 Dockerfile 中使用 ARG
4 2026 前沿视角：ARG 在现代 AI 辅助开发中的角色
5 高级技巧：多阶段构建与 ARG 作用域
6 进阶应用场景：结合 ARG 与 ENV 实现动态配置
7 实际案例分析：供应链安全与密钥管理
8 2026 工程化实践：构建性能与可观测性
9 总结：面向未来的 Dockerfile 编写之道

重新认识构建时变量：ARG 指令基础

简单来说，Docker ARG 是一种专门用于定义构建时变量（Build-time Variables）的机制。这意味着这些变量仅在执行 docker build 命令创建镜像的过程中存在和生效。一旦构建完成，这些变量（除非通过某种方式持久化）就会随风而去，不会存在于最终产生的镜像或运行的容器中。

你可以把 ARG 想象成建筑工地上临时的“施工图纸备注”。在盖楼（构建镜像）的时候，我们需要知道墙壁该刷成什么颜色（变量值），但楼房盖好之后，墙壁上并不会留下那些备注文字，只留下了刷好的颜色。

ARG 的基本语法

ARG 指令的语法非常直观，通常由变量名和可选的默认值组成：

# 定义一个带有默认值的 ARG
ARG [=]

# 也可以定义一个没有默认值的 ARG，构建时必须传值
ARG

ARG 与 ENV 的本质区别：深入理解

在深入 ARG 之前，我们需要先理清它的“双胞胎兄弟”——Docker ENV。这两者虽然都涉及变量，但用途截然不同。ENV 指令用于定义环境变量（Environment Variables）。这些变量不仅会在构建过程中生效，更重要的是，它们会被持久化保存到最终的镜像中。当你启动容器时，这些变量依然存在，应用程序可以通过读取它们来获取数据库连接字符串、API 密钥或运行时配置。

关键区别总结：

ARG：给 docker build 看的，用于控制构建过程（如选择安装版本、控制编译选项）。容器运行时默认不可见。
ENV：给运行的应用程序看的，用于配置运行环境。容器运行时依然存在。

为了让你更直观地理解这两者的区别，我们通过一个对比表格来看一下：

特性

Docker ARG

Docker ENV :—

:—

:— 主要作用域

构建时（Build Time）

运行时（Run Time） & 构建时 持久性

不会保留在最终镜像层中（除非通过 ENV 映射）

会保留在最终镜像层中 生命周期

仅在 docker build 执行期间有效

从构建开始一直延续到容器销毁 典型用途

控制软件版本、传递 HTTP 代理、设置构建路径

定义数据库 URL、设置字符编码、API 密钥 容器内可见性

不可直接访问

应用程序可直接读取

实战指南：如何在 Dockerfile 中使用 ARG

让我们通过一系列循序渐进的步骤，从最简单的例子开始，逐步掌握 ARG 的强大功能。

步骤 1：ARG 的基础用法——默认值

首先，我们创建一个简单的 Dockerfile 来演示 ARG 的基本工作原理。

#### 代码示例：基础 ARG 定义

# 基于最新的 Ubuntu 镜像
FROM ubuntu:latest

# 定义一个名为 GREET 的 ARG 变量，并设置默认值为 "Welcome"
# 如果构建时未指定值，Docker 将使用此默认值
ARG GREET=Welcome

# 在构建过程中使用 ARG 变量
# 注意：这里使用的是 Shell 变量替换语法 $GREET
RUN echo "Constructing image... Message is: $GREET" > /usr/share/message.txt

# 容器启动时打印消息
CMD cat /usr/share/message.txt

在这个例子中，INLINECODE860ce7e7 变量在 INLINECODEd9a9ec01 命令执行时被替换成了默认值 "Welcome"。这意味着无论谁运行这个容器（只要不修改构建参数），都会看到 "Welcome"。

步骤 2：覆盖 ARG 默认值

ARG 真正的威力在于我们可以在构建时覆盖它，而无需修改 Dockerfile 文件本身。

#### 使用 –build-arg 覆盖参数

现在，让我们在构建命令中传入一个不同的值：

# 使用 --build-arg 选项覆盖默认值
sudo docker build -t arg-demo-custom --build-arg GREET="Hello from Docker" .

再次运行新构建的容器：

sudo docker run arg-demo-custom

输出结果：

Constructing image... Message is: Hello from Docker

你可以看到，虽然 Dockerfile 代码没有变，但通过传递不同的构建参数，我们改变了镜像内部的内容。

2026 前沿视角：ARG 在现代 AI 辅助开发中的角色

在 2026 年，随着 Agentic AI（自主 AI 代理）和 Vibe Coding（氛围编程）的兴起，Dockerfile 的编写方式也发生了微妙的演变。我们越来越多地让 AI 辅助生成基础设施代码，而 ARG 指令成为了人类意图与 AI 自动化构建流程之间的“握手协议”。

AI 驱动的多环境构建

在使用如 Cursor 或 Windsurf 这样的现代 IDE 时，我们可能会要求 AI：“帮我准备一个适合高性能计算环境的 Node.js 镜像”。AI 生成的 Dockerfile 很可能会包含大量的 ARG 指令，因为这是在不修改代码逻辑的情况下，让构建脚本具有“推断能力”的最佳方式。

ARG 允许我们将构建决策参数化，这对于需要动态调整构建上下文的 AI 代理至关重要。例如，AI 可以根据代码库的依赖分析结果，动态决定是否在构建时传入 BUILD_OPTIMIZED=true，从而触发不同的编译优化路径。

高级技巧：多阶段构建与 ARG 作用域

在复杂的应用程序中，我们通常会使用多阶段构建来减小镜像体积。在这里，ARG 的作用域规则变得尤为重要。

动态选择基础镜像

这是 Docker 高级用法中的“神技”。我们可以用 ARG 来定义 FROM 指令的镜像版本。这听起来很简单，但在实际工程中，它极大地提高了 Dockerfile 的复用性。

#### 代码示例：使用 ARG 动态选择基础镜像

# 1. 声明 ARG（在 FROM 之前，仅用于构建上下文）
# 注意：这里的 ARG 必须在第一个 FROM 之前声明才能在 FROM 中使用
ARG NODE_VERSION=18

# 2. 使用 ARG 变量作为基础镜像标签
FROM node:${NODE_VERSION}-alpine

# 3. 在构建阶段中再次声明 ARG，以便在此阶段后续步骤使用
# 如果不再次声明，RUN 指令将无法访问 NODE_VERSION
ARG NODE_VERSION

# 验证版本
RUN echo "Building with Node version $NODE_VERSION" && \
    node -v

WORKDIR /app
COPY . .
RUN npm install --production
CMD ["node", "index.js"]

为什么这样写？

在第一个 INLINECODE5d198021 之前声明的 INLINECODEb91c684a 之所以能被 FROM 使用，是因为 Docker 引擎在解析 Dockerfile 时会优先提取这些全局变量。但是，一旦进入了某个特定的构建阶段，之前的 ARG 就会失效（除非再次声明）。

这种技术在需要频繁切换基础镜像版本（例如从 Node 18 测试升级到 Node 20）时非常有用，因为我们只需要修改构建命令的一行参数，而无需触碰 Dockerfile 的任何逻辑。

构建命令示例

# 使用 Node 20 构建，完全不需要修改 Dockerfile
sudo docker build -t my-node-app --build-arg NODE_VERSION=20 .

进阶应用场景：结合 ARG 与 ENV 实现动态配置

在实际开发中，单纯使用 ARG 往往不够灵活，因为 ARG 在构建结束后就消失了。如果我们希望构建时的参数能变成容器运行时的环境变量，就需要将 ARG 和 ENV 结合起来使用。

这是一个非常常见的最佳实践，特别是在处理版本号和构建元数据时。

代码示例：构建时变量传递给运行时环境

FROM node:18-alpine

# 定义构建时的版本号变量
ARG APP_VERSION=1.0.0
# 定义构建时的环境标识（如 dev, staging, prod）
ARG BUILD_ENV=development

# 将 ARG 映射为 ENV，这样容器内的应用就能读取到了
ENV APP_VERSION=${APP_VERSION}
ENV BUILD_ENV=${BUILD_ENV}

WORKDIR /app

# 模拟应用代码：根据构建环境写入不同的配置
RUN echo "App Version: $APP_VERSION" > /app/config.txt && \
    if [ "$BUILD_ENV" = "production" ]; then \
        echo "Optimization: Enabled" >> /app/config.txt; \
    else \
        echo "Optimization: Disabled" >> /app/config.txt; \
    fi

CMD ["sh", "-c", "cat /app/config.txt && sleep 300"]

实际案例分析：供应链安全与密钥管理

随着软件供应链安全在 2026 年变得至关重要，如何安全地使用 ARG 传递密钥成为了每个开发者必须掌握的技能。

常见陷阱：不要在 ARG 中硬编码敏感信息

虽然 ARG 很方便，但我们必须记住：ARG 的值可能会保留在镜像的历史记录中。

假设你在构建时通过 INLINECODEb6fc7525 传递了一个 Token，并在 Dockerfile 中使用了 INLINECODEbead3e04。虽然 Docker 23.x+ 版本尝试对 --build-arg 传递的敏感值进行掩码处理，但 Shell 历史或进程列表仍可能泄露这些信息。

推荐方案：使用 BuildKit 的 Secret 功能

在现代 Docker 构建中（默认使用 BuildKit），我们应该使用 INLINECODE8d5f5a46 类型和 INLINECODEd4be6854 来处理敏感信息，而不是 ARG。

#### 代码示例：安全地使用私有 NPM 令牌

# syntax=docker/dockerfile:1

FROM node:18-alpine

# 定义一个 ARG 用于非敏感的配置（如 URL）
ARG NPM_REGISTRY_URL=https://registry.npmjs.org

# 使用 BuildKit 的 secret 功能挂载密钥
# 注意：这里不直接使用 ARG 传递 Token
RUN --mount=type=secret,id=npm_token \
    npm config set registry $NPM_REGISTRY_URL && \
    npm config set //registry.npmjs.org/:_authToken $(cat /run/secrets/npm_token) && \
    npm install

# 清理环境
RUN npm config delete //registry.npmjs.org/:_authToken

2026 工程化实践：构建性能与可观测性

除了基础的用法，作为 2026 年的开发者，我们还需要关注构建性能和系统可观测性。在这一部分，我们将分享我们在生产环境中总结的一些高级技巧。

构建缓存与 ARG 的博弈

在使用 ARG 时，我们必须非常小心构建缓存。Docker 的构建缓存是分层缓存的，这意味着如果 ARG 的值发生变化，后续所有依赖该 ARG 的层都会失效。

让我们看一个反面教材：

ARG GIT_COMMIT_HASH
RUN echo $GIT_COMMIT_HASH > /app/commit.txt
RUN npm install # 这一步也会重新执行！

在这个例子中，每次我们修改 INLINECODE5a80f864，INLINECODE692f5d22 都会重新运行，这大大增加了构建时间。

优化策略：将易变的 ARG 后置

我们应该将那些经常变化的 ARG（如版本号、Commit Hash）移到 Dockerfile 的后面，或者利用 BuildKit 的缓存挂载功能。

FROM golang:1.21-alpine AS builder

# 定义默认值
ARG VERSION=1.0.0

# 先复制依赖文件（利用缓存）
COPY go.mod go.sum ./
RUN go mod download

# 再复制代码
COPY . .

# 最后才注入易变的 ARG 进行编译
# 这样只有这一层会失效，依赖下载层依然可以利用缓存
ARG VERSION
RUN go build -ldflags="-X main.Version=$VERSION" -o /app/main .

可观测性：注入构建元数据

在现代云原生架构中，搞清楚“这个镜像是怎么构建的”和“运行的是哪个版本的代码”至关重要。我们建议通过 ARG 注入 Git 信息，并利用 BuildKit 的强大功能。

# 声明构建参数
ARG BUILD_DATE
ARG VCS_REF
ARG VERSION=v0.0.0

# 添加标签
LABEL org.opencontainers.image.created="${BUILD_DATE}"
LABEL org.opencontainers.image.revision="${VCS_REF}"
LABEL org.opencontainers.image.version="${VERSION}"

# 同时注入到应用中，供运行时读取
ENV APP_VERSION=${VERSION}
ENV GIT_COMMIT=${VCS_REF}

构建时，我们通常配合 CI/CD 系统来传递这些值：

sudo docker build \
  --build-arg BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  --build-arg VCS_REF=$(git rev-parse --short HEAD) \
  --build-arg VERSION=$(git describe --tags --always) \
  -t myapp:latest .

总结：面向未来的 Dockerfile 编写之道

通过这篇深入的文章，我们不仅学习了 Docker ARG 指令的基础用法，还探讨了它在多阶段构建、动态版本选择以及与现代 AI 辅助开发流程结合时的应用场景。

核心要点回顾：

ARG 是构建时的：它只在 docker build 期间存在，用于控制镜像的生成过程。
ENV 是运行时的：它会持久化到镜像中，用于配置应用程序的运行环境。
结合使用：通过 INLINECODE897db84b 接收参数，再通过 INLINECODE1c072e01 赋值，是实现从构建到运行配置流转的标准模式。
多阶段构建中的作用域：在每个 FROM 后重新声明 ARG，或者利用全局 ARG 动态选择基础镜像。
安全第一：在 2026 年，请优先使用 BuildKit Secret 替代 ARG 传递敏感凭证，以符合严格的安全合规要求。

掌握了 ARG 指令，你的 Dockerfile 将不再是死板的脚本，而是一个灵活、可复用的配置模板。接下来，不妨回到你自己的项目中，结合我们讨论的这些高级技巧，看看哪些配置可以通过 ARG 进行优化，让构建过程更加自动化、智能化且安全。

投稿给我们	如何建站？
vps是什么？	如何安装宝塔？
如何通过博客赚钱？	便宜wordpress托管方案
免费wordpress主题	这些都是免费方案

豆丁博客