如何从docker-compose.yaml为Next.js客户端组件配置.env变量？

要让客户端组件直接使用从docker-compose传递的服务端URL变量，核心是遵守Next.js的环境变量规则，同时确保变量能正确传递到应用中，步骤如下：

1. 给变量添加NEXT_PUBLIC_前缀 #

Next.js仅会将以NEXT_PUBLIC_开头的环境变量暴露给客户端组件，因此必须把你的服务端URL变量命名为类似NEXT_PUBLIC_API_SERVER_URL的格式。

2. 在docker-compose.yaml中传递变量 #

根据你的使用场景，选择以下两种方式之一：

方式一：直接在docker-compose中定义变量 #

在服务的environment字段中直接声明变量：

services:
  nextjs-app:
    build: .
    environment:
      - NEXT_PUBLIC_API_SERVER_URL=http://your-backend-service:8080
    ports:
      - "3000:3000"

方式二：从本地.env文件加载变量 #

如果变量值存放在项目根目录的.env文件中，使用env_file字段加载：

services:
  nextjs-app:
    build: .
    env_file:
      - .env
    ports:
      - "3000:3000"

此时.env文件内容需为：

NEXT_PUBLIC_API_SERVER_URL=http://your-backend-service:8080

3. 确保构建阶段能获取变量（可选） #

如果你的Dockerfile包含next build步骤，需要确保构建阶段能拿到该变量，避免客户端代码注入失败：

• 修改Dockerfile，添加构建参数并设置环境变量：

# 声明构建参数
ARG NEXT_PUBLIC_API_SERVER_URL
# 将参数转为环境变量，供构建阶段使用
ENV NEXT_PUBLIC_API_SERVER_URL=$NEXT_PUBLIC_API_SERVER_URL

# 安装依赖
RUN npm install
# 执行构建
RUN npm run build
# 启动应用
CMD ["npm", "start"]

• 在docker-compose.yaml的build.args中传递变量：

services:
  nextjs-app:
    build:
      context: .
      args:
        - NEXT_PUBLIC_API_SERVER_URL=http://your-backend-service:8080
    environment:
      - NEXT_PUBLIC_API_SERVER_URL=http://your-backend-service:8080
    ports:
      - "3000:3000"

4. 在客户端组件中使用变量 #

在客户端组件（需添加'use client'指令）中直接通过process.env访问：

'use client';

export default function ClientApiComponent() {
  const apiBaseUrl = process.env.NEXT_PUBLIC_API_SERVER_URL;

  // 示例：发起API请求
  const fetchData = async () => {
    const res = await fetch(`${apiBaseUrl}/api/data`);
    const data = await res.json();
    console.log(data);
  };

  return (
    <div>
      <button onClick={fetchData}>获取数据</button>
    </div>
  );
}

注意事项 #

• 不要在客户端组件中使用不带NEXT_PUBLIC_前缀的变量，Next.js会自动屏蔽这类变量，防止敏感信息泄露。
• docker-compose传递的环境变量会覆盖Dockerfile中定义的同名变量，确保配置优先级符合你的需求。

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