Dockerfile构建时ARG变量未识别 报groupadd --gid缺少参数错误

ARG是Docker 构建阶段（执行docker build时） 生效的变量，不会在容器创建（docker run）阶段自动赋值。你现在的报错本质是执行build命令时没有传入这三个参数的值，导致${GROUP_ID}、${USER_NAME}被解析为空字符串，groupadd命令拿不到--gid对应的参数值直接报错。
额外注意：FROM指令会清空它之前声明的所有ARG变量，你现在把ARG写在FROM之后的位置语法是对的，但只要不在build命令中显式传值，这些变量就会保持空值。

根据你是要构建时固定用户信息，还是运行时动态传参选对应方案即可。

方案1：构建时传参（改动最小，适配固定宿主机权限场景） #

1. 先给ARG设置默认值，避免漏传参直接构建失败，修改后的Dockerfile如下：

   FROM matthewfeickert/docker-python3-ubuntu:latest
   # 配置默认值，不传参时用默认值构建
   ARG USER_NAME=devuser
   ARG USER_ID=1000
   ARG GROUP_ID=1000
   
   RUN groupadd -r --gid ${GROUP_ID} ${USER_NAME}
   # 原写法缺-m参数，不会自动创建用户家目录，后续运行容易出现权限问题，这里补上
   RUN useradd --no-log-init -r -g ${GROUP_ID} -u ${USER_ID} -m ${USER_NAME}
   
   USER ${USER_NAME}
   WORKDIR /usr/local/src
   

2. 构建时通过--build-arg传入你需要的参数值，示例命令：

   docker build \
     --build-arg USER_NAME=your_username \
     --build-arg USER_ID=$(id -u) \
     --build-arg GROUP_ID=$(id -g) \
     -t your_custom_image .
   

方案2：运行时动态指定用户（适配多环境复用镜像场景） #

如果需要在docker run阶段才指定UID/GID（比如同一个镜像要在不同宿主机上运行，匹配不同宿主机的用户ID），ARG无法实现这个需求，需要把用户创建逻辑放到容器启动脚本中：

1. 编写entrypoint.sh启动脚本：

   #!/bin/bash
   set -e
   # 启动时动态创建用户组和用户
   groupadd -r --gid ${GROUP_ID} ${USER_NAME}
   useradd --no-log-init -r -g ${GROUP_ID} -u ${USER_ID} -m ${USER_NAME}
   # 修正工作目录权限
   chown -R ${USER_NAME}:${USER_NAME} /usr/local/src
   # 切换到普通用户执行传入的命令
   exec gosu ${USER_NAME} "$@"
   

2. 修改Dockerfile，用ENV接收运行时传入的环境变量，配置启动入口：

   FROM matthewfeickert/docker-python3-ubuntu:latest
   # 安装gosu用于用户切换，避免sudo的tty问题
   RUN apt-get update && apt-get install -y --no-install-recommends gosu && rm -rf /var/lib/apt/lists/*
   
   ENV USER_NAME=devuser \
       USER_ID=1000 \
       GROUP_ID=1000
   
   COPY entrypoint.sh /usr/local/bin/entrypoint.sh
   RUN chmod +x /usr/local/bin/entrypoint.sh
   
   WORKDIR /usr/local/src
   ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
   

3. 启动容器时通过-e传入参数即可：

   docker run -it \
     -e USER_NAME=your_username \
     -e USER_ID=$(id -u) \
     -e GROUP_ID=$(id -g) \
     your_custom_image bash
   

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