如何向Docker容器中的Next.js应用传递环境变量？

1. 确保构建阶段能获取环境变量 #

Next.js中带NEXT_PUBLIC_前缀的变量是在构建阶段嵌入客户端代码的，仅在容器运行时传递变量无法生效。需保证构建过程能访问到变量：

• 修改docker-compose.yaml，在build部分添加参数传递：

version: "3.8"
services:
  client:
    build:
      context: ./client
      args:
        NEXT_PUBLIC_SERVER_URL: ${NEXT_PUBLIC_SERVER_URL}
    ports:
      - "3000:3000"
    env_file:
      - .env.local

• 在./client/Dockerfile中添加ARG和ENV声明，让构建阶段读取变量：

FROM node:18-alpine

WORKDIR /app

ARG NEXT_PUBLIC_SERVER_URL
ENV NEXT_PUBLIC_SERVER_URL=$NEXT_PUBLIC_SERVER_URL

COPY package*.json ./
RUN npm install

COPY . .
RUN npm run build

EXPOSE 3000
CMD ["npm", "start"]

2. 检查.env.local文件格式 #

• 变量定义不能有多余空格，必须是NEXT_PUBLIC_SERVER_URL=http://localhost:80（等号前后无空格）
• 确认文件编码为UTF-8，无特殊字符干扰

3. 清理Docker缓存并重启容器 #

缓存可能导致新变量未生效，执行以下命令：

docker-compose down
docker-compose build --no-cache
docker-compose up -d

4. 验证变量是否传入容器 #

进入容器检查环境变量是否存在：

docker exec -it <你的容器名称或ID> sh
echo $NEXT_PUBLIC_SERVER_URL

如果输出为空，检查：

• .env.local路径是否正确（相对于docker-compose.yaml所在目录）
• 文件是否被.dockerignore或.gitignore排除

5. 确认Next.js运行模式 #

• 开发模式（npm run dev）：Next.js会实时读取.env.local，需确保容器内能访问该文件（可在Dockerfile中复制.env.local到容器）
• 生产模式（npm run start）：变量必须在构建阶段注入，否则客户端代码无法读取

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