将NextJS应用部署到Kubernetes集群：环境变量读取异常问题

核心原因拆解 #

1. next.config.js的执行时机问题 #

next.config.js是在构建阶段（next build）执行的，而Kubernetes Secrets注入的环境变量要到Pod运行阶段才生效。构建过程中这些变量根本不存在，所以在next.config.js里打印process.env自然会输出undefined——你通过printenv能看到变量，是因为此时Pod已经运行，环境变量已注入容器，但这时候next.config.js早就执行完了。

2. Next.js环境变量的加载规则 #

• 客户端代码（页面、组件等）只能访问前缀为NEXT_PUBLIC_的变量，这类变量会在构建时被打包进静态资源；
• 服务端代码（API路由、getServerSideProps等）可以直接读取运行时的环境变量，但前提是不要在next.config.js这种构建阶段执行的文件里提前获取。

3. 可能的配置笔误 #

你提到的secretAddRef是错误字段，正确写法是secretKeyRef。不过既然printenv能看到变量，说明这个配置大概率已经修正，但还是要确认Deployment的env段格式是否正确：

env:
  - name: YOUR_VARIABLE_NAME
    valueFrom:
      secretKeyRef:
        name: your-secret-name
        key: your-secret-key

针对性解决方法 #

方法1：如果必须在next.config.js中用变量（适合不常变更的场景） #

因为next.config.js在构建时执行，所以得在构建镜像时就把变量传进去。可以修改Dockerfile：

ARG YOUR_VARIABLE_NAME
ENV YOUR_VARIABLE_NAME=$YOUR_VARIABLE_NAME

RUN npm run build

构建镜像时传入参数：

docker build --build-arg YOUR_VARIABLE_NAME=your-secret-value -t your-next-image:latest .

这种方式的缺点是失去了K8s Secrets动态更新的优势，适合不需要频繁修改的变量。

方法2：运行时直接在业务代码中读取（推荐） #

放弃在next.config.js里打印process.env的操作，直接在服务端代码中使用变量：

• 比如写一个API路由pages/api/check-secret.js：

export default function handler(req, res) {
  res.status(200).json({ secret: process.env.YOUR_VARIABLE_NAME })
}

访问这个接口就能看到正确的变量值，因为服务端代码是在Pod运行时执行的，能读取到容器的环境变量。

• 如果是客户端需要的变量，给变量加上NEXT_PUBLIC_前缀，然后直接在组件里用process.env.NEXT_PUBLIC_YOUR_VARIABLE即可。

方法3：用自定义服务器+serverRuntimeConfig（进阶场景） #

如果确实需要在next.config.js关联运行时变量，可以通过自定义服务器实现：

1. 项目根目录创建server.js：

const { createServer } = require('http')
const { parse } = require('url')
const next = require('next')

const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev })
const handle = app.getRequestHandler()

app.prepare().then(() => {
  createServer((req, res) => {
    const parsedUrl = parse(req.url, true)
    handle(req, res, parsedUrl)
  }).listen(3000, (err) => {
    if (err) throw err
    console.log('> Ready on http://localhost:3000')
  })
})

2. 修改next.config.js：

module.exports = {
  serverRuntimeConfig: {
    mySecret: process.env.YOUR_VARIABLE_NAME
  }
}

3. 在服务端代码中通过serverRuntimeConfig访问：

export async function getServerSideProps(context) {
  const { mySecret } = context.serverRuntimeConfig
  return { props: { mySecret } }
}

验证步骤 #

1. 确认变量确实注入Pod：

kubectl exec -it your-pod-name -- printenv YOUR_VARIABLE_NAME

2. 测试服务端代码：访问上面写的/api/check-secret接口，看是否返回正确值；
3. 测试客户端代码：用NEXT_PUBLIC_前缀的变量，在组件中打印process.env.NEXT_PUBLIC_YOUR_VARIABLE，确认能正常获取。

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