基于GitOps与Docker实现Next.js运行时环境变量配置方案咨询

一、Next.js 环境变量核心区分 #

Next.js 对环境变量有明确的使用规则：

• 公开变量：必须以 NEXT_PUBLIC_ 为前缀，可在客户端组件中直接读取，运行时注入后会被嵌入到页面代码中。
• 私有变量：无需前缀，仅能在服务端组件、API 路由或中间件中使用，不会暴露给客户端。

要实现运行时动态注入，必须放弃构建阶段的 .env 文件（这类文件会被打包进构建产物，无法动态修改），改用容器运行时的环境变量传递。

二、Docker 打包适配运行时注入 #

修改 Dockerfile，确保构建产物仅包含静态代码和依赖，启动时直接读取容器环境变量：

# 构建阶段：生成Next.js编译产物
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

# 运行阶段：仅保留必要文件，用next start启动（支持运行时读环境变量）
FROM node:18-alpine AS runner
WORKDIR /app
ENV NODE_ENV production

# 复制构建产物
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json

# 启动命令：运行时动态读取环境变量
CMD ["npm", "start"]

这样打包的镜像启动时，会直接读取容器的环境变量，无需在镜像中硬编码任何配置。

三、GitOps 管理配置与密钥 #

结合 GitOps 流程，核心思路是将配置/密钥以加密或明文形式存于 Git 仓库，通过 GitOps 工具同步到集群并注入容器。

1. 配置与密钥的存储方式 #

• 公开配置：直接以明文 YAML（ConfigMap）存于 Git 仓库，比如接口地址、环境标识等。
• 私有密钥：用加密工具（如 Sealed Secrets）将密钥加密后存于 Git 仓库，只有集群内的控制器能解密，避免明文泄露。

2. Kubernetes 部署时注入环境变量 #

以 Kubernetes 为例，通过 ConfigMap 和 Secret 挂载环境变量：

公开配置（ConfigMap）

apiVersion: v1
kind: ConfigMap
metadata:
  name: nextjs-public-config
data:
  NEXT_PUBLIC_API_URL: "https://api.yourdomain.com"
  APP_ENV: "production"

私有密钥（Secret，加密后存 Git）

apiVersion: v1
kind: Secret
metadata:
  name: nextjs-secrets
type: Opaque
data:
  DB_PASSWORD: <base64加密后的密码>
  API_AUTH_KEY: <base64加密后的密钥>

部署文件挂载环境变量

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nextjs-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nextjs-app
  template:
    metadata:
      labels:
        app: nextjs-app
    spec:
      containers:
      - name: nextjs-app
        image: your-registry/nextjs-app:latest
        env:
          # 从ConfigMap导入公开变量
          - name: NEXT_PUBLIC_API_URL
            valueFrom:
              configMapKeyRef:
                name: nextjs-public-config
                key: NEXT_PUBLIC_API_URL
          # 从Secret导入私有密钥
          - name: DB_PASSWORD
            valueFrom:
              secretKeyRef:
                name: nextjs-secrets
                key: DB_PASSWORD
        ports:
        - containerPort: 3000

3. GitOps 同步流程 #

1. 将上述 ConfigMap、加密后的 Secret、Deployment 文件存于 Git 仓库的指定目录（如 k8s/nextjs/）。
2. 用 GitOps 工具（如 Argo CD、Flux CD）监听该仓库，一旦有代码提交，自动将配置同步到 Kubernetes 集群。
3. 密钥更新时，先加密新密钥并提交到 Git，GitOps 工具会自动同步解密并更新 Secret，触发 Pod 滚动更新以读取新变量。

四、Next.js 中读取运行时变量 #

• 服务端组件/API 路由：直接通过 process.env.DB_PASSWORD 读取私有变量。
• 客户端组件：仅能读取 NEXT_PUBLIC_ 前缀的变量，比如 process.env.NEXT_PUBLIC_API_URL，运行时会自动注入到客户端代码中。

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