构建时需环境变量的Next.js应用DevOps流程优化咨询

针对你遇到的Kinde认证服务要求构建阶段传入环境变量，但又想遵循「构建一次，部署至全环境」的DevOps最佳实践问题，提供以下几种可行方案，按优先级排序：

1. 修正Next.js环境变量使用逻辑（优先推荐） #

Next.js中，非NEXT_PUBLIC_前缀的环境变量仅在服务器端（API路由、服务器组件、后端逻辑）生效，这些变量是运行时读取的，不需要在构建阶段提前注入。

如果你的Kinde配置是用于服务器端认证逻辑（比如API路由、服务器组件中的Kinde SDK调用），可以直接将Kinde的配置改为运行时读取环境变量，而非在构建阶段打包进代码：

示例代码调整 #

// app/api/auth/[kindeAuth]/route.js
import { handleAuth } from "@kinde-oss/kinde-nextjs-sdk/server";

export const GET = handleAuth({
  login: async (req, res) => {
    // 运行时从环境变量读取Kinde配置
    const kindeConfig = {
      clientId: process.env.KINDE_CLIENT_ID,
      clientSecret: process.env.KINDE_CLIENT_SECRET,
      issuerUrl: process.env.KINDE_ISSUER_URL,
      siteUrl: process.env.KINDE_SITE_URL,
      postLoginRedirectUrl: process.env.KINDE_POST_LOGIN_REDIRECT_URL,
      postLogoutRedirectUrl: process.env.KINDE_POST_LOGOUT_REDIRECT_URL,
    };
    // 基于动态配置处理认证流程
    return handleLogin(req, res, kindeConfig);
  },
  // 其他认证端点同理
});

这样调整后，你可以保持原有的CI/CD流程：一次构建镜像，部署时传入对应环境的.env文件即可，完全满足构建一次部署多环境的要求。

2. 使用GitHub Actions矩阵构建（适配强制构建时传参场景） #

如果Kinde SDK确实要求必须在构建阶段传入变量（比如某些静态配置逻辑），可以通过GitHub Actions的矩阵构建功能，复用构建逻辑的同时生成多环境镜像，避免重复编写CI/CD代码：

调整后的GitHub Actions配置 #

jobs:
  build-images:
    runs-on: ubuntu-latest
    # 定义环境矩阵，同时构建DEV和PROD镜像
    strategy:
      matrix:
        environment: [DEV, PROD]
    steps:
      - name: Checkout Source
        uses: actions/checkout@v4

      # 构建服务器镜像，传入对应环境的构建参数
      - name: Build server image
        working-directory: ./server
        run: |
          docker build \
            --build-arg KINDE_CLIENT_ID=${{ secrets[format('{0}_KINDE_CLIENT_ID', matrix.environment)] }} \
            --build-arg KINDE_CLIENT_SECRET=${{ secrets[format('{0}_KINDE_CLIENT_SECRET', matrix.environment)] }} \
            --build-arg KINDE_ISSUER_URL=${{ secrets[format('{0}_KINDE_ISSUER_URL', matrix.environment)] }} \
            -t my_server_image:${{ matrix.environment }} .

      - name: Publish server image to docker hub
        working-directory: ./server
        run: |
          docker login -u ${{ secrets.DOCKER_USERNAME }} -p ${{ secrets.DOCKER_PASSWORD }}
          docker push my_server_image:${{ matrix.environment }}

      # 构建客户端镜像（如果有NEXT_PUBLIC变量需要构建时传入）
      - name: Build client image
        working-directory: ./client
        run: |
          docker build \
            --build-arg NEXT_PUBLIC_SITE_URL=${{ vars[format('{0}_NEXT_PUBLIC_SITE_URL', matrix.environment)] }} \
            --build-arg KINDE_CLIENT_ID=${{ secrets[format('{0}_KINDE_CLIENT_ID', matrix.environment)] }} \
            -t my_client_image:${{ matrix.environment }} .

      - name: Publish client image to docker hub
        working-directory: ./client
        run: |
          docker login -u ${{ secrets.DOCKER_USERNAME }} -p ${{ secrets.DOCKER_PASSWORD }}
          docker push my_client_image:${{ matrix.environment }}

  deploy-server:
    runs-on: [self-hosted, linux, ${{ matrix.environment }}]
    needs: build-images
    strategy:
      matrix:
        environment: [DEV, PROD]
    environment: ${{ matrix.environment }}
    steps:
      - name: Login to docker hub
        run: docker login -u ${{ secrets.DOCKER_USERNAME }} -p ${{ secrets.DOCKER_PASSWORD }}

      - name: Pull server image from docker hub
        run: docker pull my_server_image:${{ matrix.environment }}
        
      - name: Delete old container
        run: docker rm -f server

      - name: Create env file
        run: |
          rm -f .env
          echo "MONGODB_URI=${{ secrets[format('{0}_MONGO_URI', matrix.environment)] }}" >> .env

      - name: Run docker container
        run: docker run -d -p 3001:3001 --env-file .env --name server my_server_image:${{ matrix.environment }}
  
  deploy-client:
    runs-on: [self-hosted, linux, ${{ matrix.environment }}]
    needs: build-images
    strategy:
      matrix:
        environment: [DEV, PROD]
    environment: ${{ matrix.environment }}
    steps:
      - name: Login to docker hub
        run: docker login -u ${{ secrets.DOCKER_USERNAME }} -p ${{ secrets.DOCKER_PASSWORD }}

      - name: Pull client image from docker hub
        run: docker pull my_client_image:${{ matrix.environment }}

      - name: Delete old container
        run: docker rm -f client

      - name: Create env file
        run: |
          rm -f .env
          echo "NODE_ENV=${{ vars[format('{0}_NODE_ENV', matrix.environment)] }}" >> .env
          echo "API_BASE_URL=${{ secrets[format('{0}_API_BASE_URL', matrix.environment)] }}" >> .env
          # 服务器端Kinde变量若需运行时补充，可在此添加
          echo "KINDE_CLIENT_SECRET=${{ secrets[format('{0}_KINDE_CLIENT_SECRET', matrix.environment)] }}" >> .env

      - name: Run docker container
        run: |
          cat .env
          docker run -d -p 3000:3000 --env-file .env --name client my_client_image:${{ matrix.environment }}

这种方式通过矩阵批量构建多环境镜像，复用相同的构建步骤，既满足Kinde的构建时参数要求，又尽可能遵循DevOps最佳实践。

3. 运行时拉取配置（备选复杂方案） #

如果不想分环境构建，也无法调整代码逻辑，可以在容器启动时从配置中心（如HashiCorp Vault、AWS Secrets Manager）拉取Kinde配置，注入环境变量后再启动应用：

示例Dockerfile与启动脚本 #

# 构建阶段
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# 最终运行阶段
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public
COPY --from=builder /app/package*.json ./

# 添加启动脚本
COPY start.sh .
RUN chmod +x start.sh

# 传入配置中心访问凭证
ENV CONFIG_CENTER_TOKEN=${CONFIG_CENTER_TOKEN}

CMD ["./start.sh"]

start.sh脚本示例：

#!/bin/sh
# 从配置中心拉取对应环境的Kinde配置
export KINDE_CLIENT_ID=$(curl -H "Authorization: Bearer $CONFIG_CENTER_TOKEN" https://your-config-center/api/secrets/${ENVIRONMENT}/kinde-client-id)
export KINDE_CLIENT_SECRET=$(curl -H "Authorization: Bearer $CONFIG_CENTER_TOKEN" https://your-config-center/api/secrets/${ENVIRONMENT}/kinde-client-secret)
export KINDE_ISSUER_URL=$(curl -H "Authorization: Bearer $CONFIG_CENTER_TOKEN" https://your-config-center/api/secrets/${ENVIRONMENT}/kinde-issuer-url)

# 启动Next.js应用
npm run start

此方案需要维护配置中心，增加了系统复杂度，适合对构建一致性要求极高的场景。

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