Next.js 环境变量显示 undefined 的解决方案

问题描述

当在 Next.js 项目中使用环境变量时，很多开发者会遇到 process.env.NEXT_PUBLIC_XXX 显示为 undefined 的问题。这种情况通常出现在：

在 .env.local 或 .env 文件中定义了环境变量
使用了正确的 NEXT_PUBLIC_ 前缀
但在浏览器控制台中仍然得到 undefined

核心解决方案

1. 使用正确的命名前缀

从 Next.js 9.4 版本开始，只有在环境变量名前加上 NEXT_PUBLIC_ 前缀的变量才会被暴露到浏览器端：

env

# .env.local
NEXT_PUBLIC_API_URL=http://localhost:3000/api
NEXT_PUBLIC_ANALYTICS_ID=123456789

2. 重启开发服务器

修改环境变量后，必须重启开发服务器才能生效：

bash

# 停止当前服务器
# 然后重新启动
npm run dev

服务器启动时应显示类似信息：

Loaded env from [path]/.env.local

3. 文件位置正确

确保 .env.local 文件位于项目根目录（与 package.json 同级），而不是在 src 或 app 目录内。

重要提示

环境变量是在构建时（build time）被替换的，而不是运行时（runtime）。这意味着一旦应用构建完成，环境变量的值就固定了。

不同场景下的解决方案

开发环境配置

创建多个环境文件以适应不同环境：

env

# .env - 所有环境
NEXT_PUBLIC_APP_NAME=MyApp

# .env.development - 开发环境
NEXT_PUBLIC_API_URL=http://localhost:3000/api

# .env.production - 生产环境
NEXT_PUBLIC_API_URL=https://api.myapp.com

Docker 环境

如果使用 Docker 构建，确保在构建步骤中包含环境变量：

dockerfile

# Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
# 构建时传入环境变量
RUN NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL npm run build

Next.js 12+ 配置

对于较新的 Next.js 版本，可以使用 next.config.js 配置：

javascript

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  env: {
    CUSTOM_KEY: process.env.CUSTOM_KEY,
  },
  // 或者使用 publicRuntimeConfig
  publicRuntimeConfig: {
    API_URL: process.env.NEXT_PUBLIC_API_URL,
  },
};

module.exports = nextConfig;

运行时环境变量

如果需要运行时环境变量（非构建时），可以考虑以下方案：

jsx

// 服务端组件传递环境变量到客户端
export default function ServerComponent() {
  return <ClientComponent apiUrl={process.env.API_URL} />
}

或者使用第三方库如 next-runtime-env：

jsx

// app/layout.tsx
import { PublicEnvScript } from 'next-runtime-env';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <PublicEnvScript />
      </head>
      <body>
        {children}
      </body>
    </html>
  );
}

// 在客户端组件中使用
'use client';
import { env } from 'next-runtime-env';

export default function ClientPage() {
  const apiUrl = env('NEXT_PUBLIC_API_URL');
  return <div>API URL: {apiUrl}</div>;
}

常见问题排查

检查拼写错误：临时打印所有环境变量进行调试
javascript
```
console.log(process.env);
```
避免使用 dotenv 配置：Next.js 内置了 dotenv，不需要手动配置
不要混淆 REACT_APP 和 NEXT_PUBLIC：Next.js 使用 NEXT_PUBLIC_ 前缀，不是 REACT_APP_
敏感信息保护：不要使用 NEXT_PUBLIC_ 前缀暴露敏感信息（如 API 密钥、数据库连接字符串）

版本兼容性说明

Next.js 9.4+：支持 .env.local 和 NEXT_PUBLIC_ 前缀
Next.js 12+：支持 next.config.js 中的 env 和 publicRuntimeConfig 配置
Next.js 13+（App Router）：需要考虑服务端与客户端组件的环境变量访问方式

最佳实践

开发环境下使用 .env.local
生产环境下使用构建时环境变量
敏感信息永远不要暴露到客户端
重启开发服务器以使环境变量更改生效

通过遵循上述指南，您应该能够解决 Next.js 中环境变量显示 undefined 的问题，并正确地在应用程序中使用环境变量。

相关文章

Next.js 环境变量显示 undefined 的解决方案 ​

问题描述 ​

核心解决方案 ​

1. 使用正确的命名前缀 ​

2. 重启开发服务器 ​

3. 文件位置正确 ​

不同场景下的解决方案 ​

开发环境配置 ​

Docker 环境 ​

Next.js 12+ 配置 ​

运行时环境变量 ​

常见问题排查 ​

版本兼容性说明 ​