Turbo monorepo中Next.js环境变量显示undefined求助

可能的原因及解决办法 #

1. 子包并非Next.js应用，无法自动继承环境变量注入 #

Next.js只会自动将NEXT_PUBLIC_前缀的环境变量注入到**自身应用（即apps/pages）**的客户端代码中，你的ui子包是独立的React组件库，不属于Next.js应用范畴，Next.js不会主动把环境变量注入到子包的编译流程里。

解决办法：
不在子包组件中直接读取process.env，改为通过props从父组件传递变量：

• 修改home.tsx读取变量并传递：

// apps/pages/home.tsx
import { Map } from '@your-workspace/ui';

export default function Home() {
  const mapboxToken = process.env.NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN;
  return <Map mapboxApiAccessToken={mapboxToken} />;
}

• 更新Map.tsx接收props：

// packages/ui/src/atoms/Map/Map.tsx
import React from "react";
import ReactMapGL from "react-map-gl";

interface MapProps {
  mapboxApiAccessToken: string;
}

export const Map: React.FC<MapProps> = ({ mapboxApiAccessToken }) => {
  return (
    <ReactMapGL
      mapboxApiAccessToken={mapboxApiAccessToken}
    ></ReactMapGL>
  );
};

2. dotenv-cli未正确加载目标.env文件 #

当前dev脚本dotenv -- turbo run dev默认只会加载根目录下的.env文件，若变量存在于.env.local或其他命名的环境文件中，需明确指定加载路径：

// 根目录package.json
"scripts": {
  "dev": "dotenv -e .env.local -- turbo run dev",
  // 如需同时加载多个文件：
  "dev": "dotenv -e .env -e .env.local -- turbo run dev"
}

同时确认根目录下的.env文件（如.env.local）变量名拼写完全正确：

NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=your_actual_token_here

3. Turbo环境变量传递配置遗漏 #

检查turbo.json配置，确保变量被传递到所有子包任务：

• 确认globalEnv包含目标变量，它会将变量传递给所有Turbo任务：

{
  "globalEnv": ["NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN"],
  // ...其他配置
}

• 若子包package.json有独立的dev脚本，确保该脚本未覆盖环境变量配置，能正常继承Turbo传递的变量。

4. TypeScript类型定义缺失 #

如果TypeScript无法识别process.env上的自定义变量，可能引发编译警告或间接影响运行逻辑。在项目根目录或子包中添加env.d.ts文件：

// env.d.ts
namespace NodeJS {
  interface ProcessEnv {
    NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN: string;
  }
}

并确保tsconfig.json引用该类型文件：

{
  "compilerOptions": {
    "types": ["node"]
  },
  "include": ["env.d.ts", "src/**/*"]
}

5. 缓存或进程残留问题 #

即使配置了cache: false，旧进程可能残留未更新的环境变量，尝试：

• 完全关闭所有dev服务器进程
• 删除根目录和子包下的.next、dist等编译产物目录
• 重新执行npm run dev

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