如何在Next.js客户端获取Docker传递的环境变量？

核心原因 #

Next.js的NEXT_PUBLIC_前缀环境变量是构建阶段注入客户端代码的，若变量传递时机不对（比如仅在容器启动时传入），客户端代码在构建时未拿到变量值，自然会返回undefined。以下是具体排查和解决步骤：

1. 调整环境变量传递时机 #

必须在镜像构建阶段传入NEXT_PUBLIC_BASE_URL，而非仅在容器启动时传递：

• 修改Dockerfile，通过ARG定义构建参数，再转为ENV注入构建流程：

  FROM node:16-alpine
  
  # 定义构建时参数
  ARG NEXT_PUBLIC_BASE_URL
  # 将参数转为环境变量，确保构建时注入客户端代码
  ENV NEXT_PUBLIC_BASE_URL=$NEXT_PUBLIC_BASE_URL
  
  WORKDIR /app
  COPY package*.json ./
  RUN npm install
  COPY . .
  RUN npm run build
  
  CMD ["npm", "start"]
  

• 构建镜像时显式传递参数：

  docker build --build-arg NEXT_PUBLIC_BASE_URL=https://your-domain.com -t next-app .
  

• 若用docker-compose，在build块中配置args：

  version: '3.8'
  services:
    next-app:
      build:
        context: .
        args:
          NEXT_PUBLIC_BASE_URL: https://your-domain.com
      ports:
        - "3000:3000"
  

2. 检查客户端代码引用方式 #

确保客户端代码中直接通过process.env前缀访问变量：

• 错误写法：

  const baseUrl = NEXT_PUBLIC_BASE_URL // 缺少process.env前缀
  

• 正确写法：

  const baseUrl = process.env.NEXT_PUBLIC_BASE_URL;
  

3. 清除构建缓存 #

若之前有旧镜像缓存，可能导致新变量未生效，构建时强制清除缓存：

docker build --no-cache --build-arg NEXT_PUBLIC_BASE_URL=https://your-domain.com -t next-app .

或docker-compose构建时：

docker-compose build --no-cache

4. 排查next.config.js配置冲突 #

检查项目中的next.config.js，确保没有自定义webpack配置覆盖默认的环境变量注入逻辑，比如不要手动修改DefinePlugin或env字段干扰Next.js的默认行为。

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