Docker构建阶段无法读取环境变量导致useradd报错问题排查

Docker 构建阶段和容器运行时是两个完全隔离的变量作用域，之前所有尝试不生效的核心逻辑如下：

• docker-compose.yml 中environment块配置的变量，仅在容器启动后的运行阶段生效，Dockerfile 执行RUN useradd这类构建指令时完全读取不到这部分变量。
• 无论是命令行临时注入的宿主环境变量、还是.env文件中定义的变量，都不会被自动传递给Docker构建流程，必须显式声明为构建参数才能被Dockerfile读取。
• 报错useradd: invalid user ID '-g'的直接触发逻辑：构建阶段${UID}/${GID}/${USER}三个变量全部为空，你写的useradd -u ${UID} -g ${GID} ${USER}实际执行时被解析为useradd -u -g ，命令行把紧随-u后的-g当成了UID参数值，直接触发参数非法错误。

按以下两步修改配置即可，兼容你当前用的Docker 20.10、Compose 2.6、Manjaro环境，compose v2/v3版本通用。

1. 调整Dockerfile，显式声明构建参数 #

基于alpine镜像的可直接用以下配置，加了空值兜底逻辑，避免变量缺失时报错：

FROM alpine:latest
# 声明构建阶段接收的参数，设置默认值兜底
ARG UID=1000
ARG GID=1000
ARG USER=appuser

RUN apk update && apk upgrade --no-cache \
    && apk add --no-cache shadow \
    # 先创建对应GID的用户组，避免建用户时报组不存在
    && groupadd -g ${GID} ${USER} \
    && useradd -u ${UID} -g ${GID} -m -s /bin/ash ${USER}

# 构建完成后切换到普通用户运行
USER ${USER}
WORKDIR /home/${USER}

CMD ["/bin/ash"]

2. 调整docker-compose.yml，显式传递构建参数 #

注意要在build配置块下加args字段，这部分才是传给构建阶段的参数，environment块可以保留作为运行时变量使用，不影响构建流程：

version: "2.2"
services:
  app:
    build:
      context: .
      # 显式把变量传给Dockerfile构建阶段，会自动读取宿主环境/.env中的同名变量值
      args:
        - UID
        - GID
        - USER
    environment:
      - UID
      - GID
      - USER
    # 挂载需要持久化的目录，示例为把当前项目目录挂载到容器内用户家目录下的app文件夹
    volumes:
      - ./:/home/${USER}/app

验证方式 #

直接执行你原来的启动命令即可：
docker-compose up -d --remove-orphans --build
启动后可进入容器执行id命令，看到的UID/GID和宿主当前普通用户完全一致，容器在挂载目录生成的所有文件，宿主侧普通用户可直接读写删除，完全不需要sudo权限。

避坑说明 #

• docker build 没有-u短参数，构建阶段无法通过命令行参数直接指定运行用户，所有构建阶段的传参只能通过--build-arg实现，对应到compose配置就是build.args块。
• 不要混淆ARG（构建参数）和ENV（运行时环境变量）：ARG仅在docker build执行过程中生效，容器启动后就会失效；ENV会持久存在于容器运行时环境中，两者作用域完全独立，仅配置environment传ENV不可能被构建阶段的指令读取到。
• 如果担心宿主环境变量读取异常，直接在项目根目录创建.env文件写入固定值即可，配置格式如下：

UID=1000
GID=1000
USER=你的宿主用户名

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