为何Next.js会忽略通过docker-compose传递的环境变量？

1. 排查镜像构建阶段的硬编码问题 #

• 检查Dockerfile，确保没有通过ENV指令把.env.local里的变量直接硬编码进镜像，也不要将.env.local文件复制到镜像内让应用启动时读取。
• 若是前端应用（如React/Vue），注意构建过程会把环境变量编译进静态文件，这种场景下必须改用运行时注入变量的方案，否则构建后的静态文件不会再读取运行时的环境变量。

2. 正确配置docker-compose的运行时变量传递 #

• 使用environment字段直接定义变量，或通过env_file指定外部变量文件，确保变量是传递到容器运行时的：

  services:
    your-app:
      build: .
      environment:
        - DB_HOST=db
        - API_URL=https://prod.example.com
      # 也可以用外部env文件
      # env_file:
      #   - ./prod.env
  

• 不要依赖卷挂载.env文件到容器内，除非你的应用明确会在启动时重新读取该文件（多数框架构建完成后不会再读取本地.env文件）。

3. 调整应用启动逻辑，优先读取运行时变量 #

• 后端应用：确保启动时优先读取容器的环境变量，而非构建阶段的.env.local。比如Node.js直接用process.env.VAR_NAME，不要在构建时将变量写入静态配置文件。
• 前端应用：如果需要运行时变量，可在容器启动脚本中添加替换逻辑，示例如下：

  # start.sh 启动脚本
  sed -i "s/__API_URL__/$API_URL/g" /usr/share/nginx/html/js/*.js
  nginx -g "daemon off;"
  

  然后在Dockerfile中设置启动命令为该脚本：

  COPY start.sh /start.sh
  RUN chmod +x /start.sh
  CMD ["/start.sh"]
  

4. 验证变量是否正确传递到容器 #

• 启动容器后，进入容器查看环境变量是否存在：

  docker exec -it <容器名称> env
  

• 如果变量存在但应用未读取，检查应用的配置加载顺序，确保运行时变量优先级高于构建时的静态配置。

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