Next.js Docker Compose构建时动态传递环境变量失败求助

Next.js应用会在构建阶段打包环境变量，因此需要将环境变量作为构建参数（build args）传入构建阶段。作为CI/CD流水线的一部分，希望通过compose.yaml中声明的环境变量动态传递这些参数，但构建时无法读取compose文件中的环境变量，终端输出警告：
time="2024-12-12T23:35:10-05:00" level=warning msg="The \"NEXT_PUBLIC_GRAPHQL_SERVER\" variable is not set. Defaulting to a blank string."

相关配置 #

Compose.yaml #

services:
  frontend:
    build:
      context: ./frontend
      args:
        - NEXT_PUBLIC_GRAPHQL_SERVER=${NEXT_PUBLIC_GRAPHQL_SERVER}
    env_file:
      - ./frontend/.env
    environment:
      NODE_ENV: production
      NEXT_PUBLIC_GRAPHQL_SERVER: http://localhost:3000/
    ports:
      - 8080:8080

Dockerfile #

FROM base AS builder
WORKDIR /usr/src/app

COPY --from=deps /usr/src/app/node_modules ./node_modules
COPY . .
ARG NEXT_PUBLIC_GRAPHQL_SERVER
ENV NEXT_PUBLIC_GRAPHQL_SERVER=${NEXT_PUBLIC_GRAPHQL_SERVER}
RUN npm run build

注：在args中显式设置环境变量时一切正常，但不符合动态工作流的需求。

解决方法 #

问题核心是Compose构建阶段无法直接读取自身environment字段定义的变量，${NEXT_PUBLIC_GRAPHQL_SERVER}会被Compose解析为宿主环境的变量，而非你在environment里配置的值。以下是几种实现动态传递的可行方案：

方案1：用.env文件统一管理变量 #

1. 在./frontend/.env中定义变量：

NEXT_PUBLIC_GRAPHQL_SERVER=http://localhost:3000/

2. 调整Compose.yaml，移除environment中的重复变量，让构建参数直接读取.env文件的值：

services:
  frontend:
    build:
      context: ./frontend
      args:
        - NEXT_PUBLIC_GRAPHQL_SERVER=${NEXT_PUBLIC_GRAPHQL_SERVER}
    env_file:
      - ./frontend/.env
    environment:
      NODE_ENV: production
    ports:
      - 8080:8080

Compose会自动加载.env文件中的变量，构建参数就能正确获取到对应值。

方案2：在构建块中指定env_file #

如果不想依赖宿主环境变量，可以在Compose的build块中单独指定env_file，让构建阶段直接读取文件内容：

services:
  frontend:
    build:
      context: ./frontend
      args:
        - NEXT_PUBLIC_GRAPHQL_SERVER
      env_file:
        - ./frontend/.env
    environment:
      NODE_ENV: production
      NEXT_PUBLIC_GRAPHQL_SERVER: ${NEXT_PUBLIC_GRAPHQL_SERVER}
    ports:
      - 8080:8080

这里args只写变量名，Compose会从指定的env_file中读取对应值传入构建参数。

方案3：CI/CD流水线直接注入变量 #

在CI/CD流程（如GitHub Actions、GitLab CI）中，直接通过构建命令注入变量，完全绕过Compose的变量解析：

docker compose build --build-arg NEXT_PUBLIC_GRAPHQL_SERVER=http://your-server-url/ frontend

这种方式更适配流水线的动态场景，变量可根据测试/生产等不同环境灵活配置。

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