Next.js 13中使用动态键访问环境变量返回Undefined问题

安全阿岳

2026-7-1

Next.js 13客户端组件动态读取.env变量返回undefined的解决方案

问题根源

Next.js 13对客户端环境变量采用构建时静态替换机制：只有明确写出的process.env.NEXT_PUBLIC_XXX会被替换为实际值。动态拼接的变量名（比如process.env[NEXT_PUBLIC_YANDEX_METRIKA_${page_}]）因为构建阶段无法确定具体键名，不会被工具识别并替换，所以客户端运行时process.env中不存在该键，返回undefined。

解决方案

方案1：提前映射所有可能的环境变量

手动创建映射对象，静态引用所有需要的环境变量，确保构建工具能识别替换，之后即可通过动态键访问：

const YandexMetrika: React.FC<YandexMetrikaProps> = ({ page }) => {
  // 静态定义所有页面对应的埋点ID映射
  const metrikaIdMap = {
    HOME: process.env.NEXT_PUBLIC_YANDEX_METRIKA_HOME,
    ABOUT: process.env.NEXT_PUBLIC_YANDEX_METRIKA_ABOUT,
    PRODUCT: process.env.NEXT_PUBLIC_YANDEX_METRIKA_PRODUCT,
    // 补充其他页面类型...
  };

  if (!page) return null;

  // 类型断言确保键名安全
  const currentMetrikaId = metrikaIdMap[page as keyof typeof metrikaIdMap];
  console.log(currentMetrikaId); // 正常获取值

  return null;
};

方案2：在next.config.js中批量注入环境变量

如果页面类型较多，可在配置文件中批量收集相关环境变量，客户端就能直接动态访问：

// next.config.js
module.exports = {
  env: {
    // 筛选并注入所有NEXT_PUBLIC_YANDEX_METRIKA_开头的变量
    ...Object.fromEntries(
      Object.entries(process.env).filter(([key]) => 
        key.startsWith("NEXT_PUBLIC_YANDEX_METRIKA_")
      )
    ),
  },
};

之后客户端组件可直接动态拼接键名：

const YandexMetrika: React.FC<YandexMetrikaProps> = ({ page }) => {
  if (!page) return null;

  const currentMetrikaId = process.env[`NEXT_PUBLIC_YANDEX_METRIKA_${page}`];
  console.log(currentMetrikaId); // 正常获取值

  return null;
};