Next.js Docker容器生产环境中process.env为空问题求助

问题出在Next.js环境变量的注入时机和Docker构建流程的匹配上，以下是具体原因和修复方案：

核心原因 #

Next.js的环境变量分两类：

• NEXT_PUBLIC_前缀的客户端环境变量：必须在构建阶段就被静态嵌入到前端代码中，运行时无法动态修改。
• 无前缀的服务器端环境变量：可在运行时读取，但如果是静态生成（SSG）页面，仍需构建时注入。

你当前的问题是：Dockerfile中的ENV指令是在容器运行时生效的，而Next.js构建过程（npm run build）如果发生在ENV指令之前，构建时根本拿不到这些变量，导致最终代码中没有注入process.env内容——即使容器运行时能看到环境变量，也无法被已构建好的代码读取。

修复方案 #

1. 调整Dockerfile，确保构建时能获取环境变量 #

修改Dockerfile，通过构建参数（ARG）接收变量，再转为环境变量，且必须放在npm run build之前：

# 定义构建参数，用于接收外部传入的变量
ARG NEXT_PUBLIC_API
ARG NODE_ENV

# 将构建参数转为环境变量，让Next.js构建时能读取到
ENV NEXT_PUBLIC_API=$NEXT_PUBLIC_API
ENV NODE_ENV=$NODE_ENV

# 后续执行依赖安装和构建步骤
WORKDIR /app
COPY package*.json ./
RUN npm install --production
COPY . .
RUN npm run build  # 必须在ENV设置之后执行
CMD ["npm", "start"]

2. 优化GitHub Actions工作流，传递构建参数 #

你当前的工作流里重复执行了docker build和docker/build-push-action，建议保留后者（功能更完善），并在其中传递构建参数：

jobs:
  build:
    runs-on: ubuntu-latest

    env:
      NODE_ENV: production
      NEXT_PUBLIC_API: http://example.com

    steps:
    - name: Checkout code
      uses: actions/checkout@v2
    - name: Log in to Docker Hub
      uses: docker/login-action@v1
      with:
        username: ${{ secrets.DOCKER_USERNAME }}
        password: ${{ secrets.DOCKER_PASSWORD }}
    - name: Build and Push to Docker Hub
      uses: docker/build-push-action@v2
      with:
        context: .
        push: true
        tags: aquarima/myapp:latest
        # 传递构建参数到Docker构建过程
        build-args: |
          NEXT_PUBLIC_API=${{ env.NEXT_PUBLIC_API }}
          NODE_ENV=${{ env.NODE_ENV }}

3. 验证修复效果 #

重新触发GitHub Actions构建，拉取新镜像运行后：

• 客户端代码中process.env.NEXT_PUBLIC_API应该能正常返回值
• 服务器端代码中process.env.NODE_ENV和process.env.NEXT_PUBLIC_API也能正常读取

额外提示 #

• 无需在Dockerfile和GitHub Actions中重复定义环境变量，通过构建参数传递即可避免冗余
• NODE_ENV在执行npm run build时会自动被Next.js设置为production，如果不需要额外控制可以省略手动定义

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