Azure Pipelines Docker@2构建命令无法正确传递build args参数

问题场景 #

通过azure-pipelines.yml配置容器化应用Azure构建流水线时，向docker build命令传入的所有构建参数值均为空，即使未主动传入参数、Dockerfile中已指定参数默认值时，该问题仍然存在。

问题复现代码片段 #

azure-pipelines.yml配置如下（敏感信息已脱敏）：

- task: Docker@2
  displayName: build
  inputs:
    containerRegistry: our_container_registry
    repository: $(Build.Repository.Name)
    command: build
    Dockerfile: '**/Dockerfile'
    tags: $(Build.BuildNumber)
    arguments: --build-arg BuildNumber=$(Build.BuildNumber)

已确认的环境与现象 #

• 流水线任务运行虚拟机镜像为ubuntu-latest
• 流水线打印的执行命令日志显示构建参数已正确传入：例如配置--build-arg BuildNumber=1.2.3时，日志中执行命令会完整显示该参数
• 当前使用build命令而非已知存在构建参数传递问题的buildAndPush命令，镜像推送为独立步骤，问题出现在构建阶段，未推进到推送环节
• Dockerfile中包含RUN echo Build Number: ${BuildNumber}指令，构建过程中该指令输出为Build Number: ，参数值为空
• 复制流水线日志中打印的完整docker build命令在本地执行时，可正常完成容器构建，上述echo指令可正确输出对应构建编号

根因与修复方案 #

1. 优先修正Dockerfile的ARG作用域问题 #

Docker构建参数的作用域规则为：ARG仅在声明位置到当前构建阶段结束的范围内生效。如果ARG在FROM指令前声明，后续每个构建阶段都需要单独重新声明该ARG才能读取到值（不需要重复赋值），这是最常见的导致ARG值为空的原因。
正确的Dockerfile写法示例：

# 全局ARG声明（用于FROM指令的参数替换）
ARG BuildNumber=default_value
FROM your-base-image:latest

# 必须在当前构建阶段重新声明ARG，才能读取到传入的参数值
ARG BuildNumber
RUN echo Build Number: ${BuildNumber}

2. 改用Docker@2任务原生的buildArgs字段传参 #

不要将--build-arg写在arguments字段中，Docker@2任务提供了专门的buildArgs输入参数处理构建参数，会自动处理命令拼接时的转义、引号问题，避免底层逻辑导致的参数丢失。
修改后的流水线配置：

- task: Docker@2
  displayName: build
  inputs:
    containerRegistry: our_container_registry
    repository: $(Build.Repository.Name)
    command: build
    Dockerfile: '**/Dockerfile'
    # 显式指定构建上下文，避免通配符匹配Dockerfile时上下文路径异常
    buildContext: '$(System.DefaultWorkingDirectory)'
    tags: $(Build.BuildNumber)
    # 使用原生buildArgs字段传参，多个参数用换行分隔
    buildArgs: |
      BuildNumber=$(Build.BuildNumber)

3. 兼容性修复：禁用BuildKit #

部分旧版Dockerfile逻辑与BuildKit存在兼容问题，可在构建任务前添加环境变量配置临时关闭BuildKit验证：

- script: |
    echo "##vso[task.setvariable variable=DOCKER_BUILDKIT]0"
  displayName: Disable Docker BuildKit

替代方案 #

如果Docker@2封装任务始终存在传参异常，可直接用脚本调用原生docker命令，完全控制构建流程，避免任务黑盒逻辑带来的问题：

1. 先登录容器注册表

- task: Docker@2
  displayName: Login to container registry
  inputs:
    containerRegistry: our_container_registry
    command: login

2. 直接执行docker build命令

- script: |
    docker build \
      -f $(System.DefaultWorkingDirectory)/path/to/your/Dockerfile \
      --build-arg BuildNumber=$(Build.BuildNumber) \
      -t our_container_registry/$(Build.Repository.Name):$(Build.BuildNumber) \
      $(System.DefaultWorkingDirectory)
  displayName: Build container image via docker cli

内容的提问来源于stack exchange，提问作者Jake Conkerton-Darby