Azure DevOps Pipeline中docker buildx build报错：需恰好1个参数

核心原因分析 #

你遇到的ERROR: "docker buildx build" requires exactly 1 argument错误，大概率是命令参数解析异常导致的，结合你的命令，主要排查以下几点：

1. 重复的标签键 #

你连续三次使用--label version=xxx，Docker不允许同一个标签键重复定义。重复的标签会打乱buildx的参数解析逻辑，导致它无法正确识别命令的参数边界，最终抛出参数数量错误。

2. 变量为空或格式异常 #

• 如果$commit变量为空，--label $commit会变成无效的--label （后面无值），破坏命令结构。
• ARG1、ARG2、image等变量如果未正确定义或为空，也会导致build-arg或镜像标签格式错误。
• 如果$commit包含空格、特殊字符且未转义，同样会让命令解析失败。

3. 多行命令的换行符问题 #

在Azure DevOps Pipeline的bash任务中，多行命令的\后面如果有多余空格，或者代理是Windows系统导致换行符不兼容，也可能引发参数解析错误。

具体修复步骤 #

第一步：修复重复标签 #

将三个version标签改为不同的键，避免冲突：

docker buildx build --platform linux/amd64,linux/arm64 \
                --label version-full=$(cat package.json | jq -r '.version') \
                --label version-major-minor=$(cat package.json | jq -r '.version' | cut -d '.' -f 1,2) \
                --label version-major=$(cat package.json | jq -r '.version' | cut -d '.' -f 1) \
                --label commit=$commit \
                --build-arg ARG1=${ARG1:-} \
                --build-arg ARG2=${ARG2:-} \
                -t ***.azurecr.io/$(image):$commit \
                -t ***.azurecr.io/$(image):latest \
                --push \
                .

第二步：验证变量有效性 #

• 在Pipeline任务中添加echo $commit $image $ARG1 $ARG2命令，确认所有变量都有合法值（无空值、无特殊字符）。
• 如果$commit是Git提交哈希，建议直接使用Azure DevOps内置变量$(Build.SourceVersion)（短哈希可用$(Build.SourceVersionShort)），避免自定义变量传递出错。

第三步：排查工作目录与换行符 #

• 在命令前添加pwd && ls -l，再次确认当前目录存在Dockerfile。
• 确保多行命令的\后面没有多余空格，避免解析时出现无效参数。

第四步：简化命令排查 #

先执行最简化的buildx命令，验证基础功能：

docker buildx build --platform linux/amd64,linux/arm64 -t ***.azurecr.io/$(image):test --push .

如果成功，再逐步添加标签、build-arg等参数，定位具体出错的参数项。

第五步：检查Docker buildx版本 #

Azure DevOps代理上的Docker buildx版本过低可能存在兼容性问题，可添加命令升级：

docker buildx install

内容的提问来源于stack exchange，提问作者monstermuffino