NextJS 12.2.5中NEXT_PUBLIC前缀环境变量客户端未定义问题

问题背景 #

在NextJS 12.2.5版本中，所有客户端暴露的环境变量均已添加NEXT_PUBLIC前缀，但客户端访问页面时抛出Environment variable NEXT_PUBLIC_STATIC_MUSTER_URL was not defined!错误，服务端无缺失变量提示。相关配置与代码如下：

1. .env.development配置 #

DATABASE_URL="postgresql://dbuser:dbpass@localhost:5432/db?schema=public"
NEXT_PUBLIC_STATIC_MUSTER_URL="http://localhost:8080/muster"
NEXT_PUBLIC_MUSTER_SEARCH_HOST="http://localhost:7777"
NEXT_PUBLIC_MUSTER_SEARCH_API_KEY ="key"  # 等号后存在空格
NEXT_PUBLIC_NEWS_API_KEY="another_key"
NEXT_PUBLIC_NEWS_API_URL="http://localhost:8888"
NEXT_PUBLIC_BASE_URL="http://localhost:3000"

2. utils/env.ts验证逻辑 #

function defaultValidator(key: string) {
    const value = process.env[key];

    if (value) {
        return value;
    }

    throw new Error(`Environment variable ${key} was not defined!`);
}

export const env = {
    NODE_ENV: process.env.NODE_ENV,
    NEXT_PUBLIC_STATIC_MUSTER_URL: defaultValidator("NEXT_PUBLIC_STATIC_MUSTER_URL"),
    NEXT_PUBLIC_MUSTER_SEARCH_HOST: defaultValidator("NEXT_PUBLIC_MUSTER_SEARCH_HOST"),
    NEXT_PUBLIC_MUSTER_SEARCH_API_KEY: defaultValidator("NEXT_PUBLIC_MUSTER_SEARCH_API_KEY"),
    NEXT_PUBLIC_NEWS_API_KEY: defaultValidator("NEXT_PUBLIC_NEWS_API_KEY"),
    NEXT_PUBLIC_NEWS_API_URL: defaultValidator("NEXT_PUBLIC_NEWS_API_URL"),
    NEXT_PUBLIC_BASE_URL: defaultValidator("NEXT_PUBLIC_BASE_URL"),
}

3. pages/test.tsx使用代码 #

import { env } from 'utils/env'
export default function Test() {
   return (<div>{JSON.stringify({url: env.NEXT_PUBLIC_STATIC_MUSTER_URL})}</div>)
}

客户端报错信息 #

Unhandled Runtime Error
Error: Environment variable NEXT_PUBLIC_STATIC_MUSTER_URL was not defined!

解决方案 #

1. 修复.env文件格式错误 #

.env.development中NEXT_PUBLIC_MUSTER_SEARCH_API_KEY ="key"一行的等号后存在空格，会导致环境变量解析异常，甚至影响其他变量的加载。将其修改为：

NEXT_PUBLIC_MUSTER_SEARCH_API_KEY="key"

2. 调整验证逻辑适配客户端运行 #

NextJS在构建时会将NEXT_PUBLIC_前缀的变量静态替换到客户端代码中，但原验证函数在客户端运行时，若变量未被正确注入会直接抛出错误。修改验证逻辑，仅在服务端执行严格验证：

function defaultValidator(key: string) {
    const value = process.env[key];

    // 服务端环境下强制验证变量存在
    if (typeof window === 'undefined') {
        if (!value) {
            throw new Error(`Environment variable ${key} was not defined!`);
        }
    }

    return value;
}

export const env = {
    NODE_ENV: process.env.NODE_ENV,
    NEXT_PUBLIC_STATIC_MUSTER_URL: defaultValidator("NEXT_PUBLIC_STATIC_MUSTER_URL"),
    NEXT_PUBLIC_MUSTER_SEARCH_HOST: defaultValidator("NEXT_PUBLIC_MUSTER_SEARCH_HOST"),
    NEXT_PUBLIC_MUSTER_SEARCH_API_KEY: defaultValidator("NEXT_PUBLIC_MUSTER_SEARCH_API_KEY"),
    NEXT_PUBLIC_NEWS_API_KEY: defaultValidator("NEXT_PUBLIC_NEWS_API_KEY"),
    NEXT_PUBLIC_NEWS_API_URL: defaultValidator("NEXT_PUBLIC_NEWS_API_URL"),
    NEXT_PUBLIC_BASE_URL: defaultValidator("NEXT_PUBLIC_BASE_URL"),
}

3. 重启开发服务器 #

修改.env文件后，NextJS不会自动重新加载环境变量，必须重启开发服务器才能让新配置生效。

4. 验证变量注入情况 #

若问题仍存在，可直接在客户端打印process.env变量排查是否注入成功：

export default function Test() {
   return (<div>{JSON.stringify({
       directUrl: process.env.NEXT_PUBLIC_STATIC_MUSTER_URL,
       envUrl: env.NEXT_PUBLIC_STATIC_MUSTER_URL
   })}</div>)
}

如果直接使用process.env能获取到值，说明是验证函数逻辑问题，按步骤2调整即可。

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