Next.js项目在K8s生产/QA环境中环境变量未定义问题排查

我的Next.js 14.x项目在本地开发环境、Docker容器中，API端点都能正常读取环境变量并获取有效值，但部署到K8s的生产/QA环境后，尽管Pod已配置对应环境变量，代码调用时却返回undefined。生产/QA环境Pod的环境变量已正确配置（如截图所示）。

代码调用示例 #

方式一 #

import { unstable_noStore as noStore } from 'next/cache'

export default async function ClientDataBase(): Promise<ClientProps> {
  noStore()
  const API_CLIENT = process.env.NEXT_PUBLIC_BFF_ORM_CLIENT
  if (!API_CLIENT) {
    console.log("API_CLIENT not found")
  }
// ... 其他逻辑
}

方式二 #

async function fetchData() {
  const apiTest = process.env['NEXT_PUBLIC_BFF_ORM_STATUS']
  if (!apiTest) {
    console.log("API TESTE SEM VALOR")
  }
// ... 其他逻辑
}

Dockerfile配置 #

FROM node:lts as dependencies
WORKDIR /front
COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile
FROM node:lts as builder
WORKDIR /front
COPY . .
COPY --from=dependencies /front/node_modules ./node_modules
RUN yarn build
FROM node:lts as runner
WORKDIR /front
ENV YARN_CACHE_FOLDER=/dev/shm/yarn_cache
ENV NODE_ENV production
# If you are using a custom next.config.js file, uncomment this line.
# COPY --from=builder /my-project/next.config.js ./
COPY --from=builder /front/public ./public
COPY --from=builder /front/.next ./.next
COPY --from=builder /front/node_modules ./node_modules
COPY --from=builder /front/package.json ./package.json
EXPOSE 3000
CMD ["yarn", "start"]

K8s ConfigMap配置 #

apiVersion: v1
kind: ConfigMap
metadata:
  name: [项目名称]
data: 
  NEXT_PUBLIC_BFF_ORM_CLIENT: "HELLO, WORD!"
  NEXT_PUBLIC_BFF_ORM_STATUS: "HELLO, WORD!"

排查方向及解决方案 #

1. Next.js环境变量构建时注入特性 #

Next.js的NEXT_PUBLIC_前缀环境变量会在构建阶段注入到客户端代码中，而你的Dockerfile是在builder阶段执行yarn build，此时K8s的环境变量还未注入容器，导致构建后的代码里没有这些变量值，运行时自然读取不到。

解决方法：

• 方法一：若变量仅用于服务端代码（Server Components/API Routes），直接去掉NEXT_PUBLIC_前缀，Next.js会在运行时读取容器环境变量，无需构建时注入。注意：该变量不能在客户端组件中直接使用。
• 方法二：修改构建逻辑，让NEXT_PUBLIC_变量支持运行时读取：
  在next.config.js中添加配置：

  module.exports = {
    env: {
      NEXT_PUBLIC_BFF_ORM_CLIENT: process.env.NEXT_PUBLIC_BFF_ORM_CLIENT,
      NEXT_PUBLIC_BFF_ORM_STATUS: process.env.NEXT_PUBLIC_BFF_ORM_STATUS,
    },
  }
  

  同时取消Dockerfile中复制next.config.js的注释：

  COPY --from=builder /front/next.config.js ./
  

2. K8s环境变量挂载验证 #

• 进入Pod内部确认环境变量是否存在：

  kubectl exec -it <pod-name> -- printenv | grep NEXT_PUBLIC_
  

• 若输出为空，检查Deployment配置是否正确挂载ConfigMap到容器环境变量：

  spec:
    containers:
    - name: <容器名称>
      env:
        - configMapRef:
            name: [项目名称]
  

3. 启动模式验证 #

确保K8s容器中NODE_ENV=production已正确设置，Next.js在生产模式下对环境变量的处理逻辑更严格，若构建时未注入NEXT_PUBLIC_变量，客户端代码无法读取。若需在客户端使用变量，可通过服务端API接口转发获取，避免直接在客户端读取环境变量。

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