使用NX时React应用无法读取环境变量的问题排查

问题背景 #

使用NX管理包含React应用与NestJS应用的monorepo时，NestJS应用本地和部署后都能正常读取环境变量，但React应用中process.env为空对象，environment.ts中定义的变量始终返回undefined。Webpack构建配置中能正常打印环境变量，但客户端代码无法获取。

项目结构 #

/nx-monorepo
  /apps
    /react-app
      /src
        /environments
          environment.ts
          environment.prod.ts
      .env
      ...
      webpack.config.js
    /nest-app
      /src
      .env
  nx.json
  package.json

现有配置 #

Webpack配置（webpack.config.js） #

const { composePlugins, withNx } = require('@nx/webpack');
const { withReact } = require('@nx/react');

module.exports = composePlugins(withNx(), withReact(), (config) => {        
  console.log('Environment Variables:')
  console.log('NX_FLYOUT_SERVICE_URL: ', process.env.NX_FLYOUT_SERVICE_URL);
  console.log('NX_IS_PRE_RELEASE: ', process.env.NX_IS_PRE_RELEASE);
  console.log('NX_GOOGLE_MAPS_API_KEY: ', process.env.NX_GOOGLE_MAPS_API_KEY);

  return config;
});

环境文件（environment.ts） #

type Environment = {
  production: boolean;
  flyoutServiceUrl: string | undefined;
  isPreRelease: boolean;
}

export const environment: Environment = {
  production: false,
  flyoutServiceUrl: process.env.NX_FLYOUT_SERVICE_URL,
  isPreRelease: process.env.NX_IS_PRE_RELEASE === 'true'
};

现象 #

• Webpack构建阶段能正常打印NX_前缀的环境变量
• React应用客户端代码中，process.env为空对象，environment返回{production: false, flyoutServiceUrl: undefined, isPreRelease: false}

解决方法 #

1. 显式配置Webpack的DefinePlugin #

withNx()插件理论上会自动注入环境变量，但部分场景下需要手动配置确保变量被替换到客户端代码。修改webpack.config.js：

const { composePlugins, withNx } = require('@nx/webpack');
const { withReact } = require('@nx/react');
const webpack = require('webpack');

module.exports = composePlugins(withNx(), withReact(), (config) => {        
  console.log('Environment Variables:')
  console.log('NX_FLYOUT_SERVICE_URL: ', process.env.NX_FLYOUT_SERVICE_URL);
  console.log('NX_IS_PRE_RELEASE: ', process.env.NX_IS_PRE_RELEASE);
  console.log('NX_GOOGLE_MAPS_API_KEY: ', process.env.NX_GOOGLE_MAPS_API_KEY);

  // 显式注入NX前缀的环境变量到客户端
  config.plugins.push(
    new webpack.DefinePlugin({
      'process.env.NX_FLYOUT_SERVICE_URL': JSON.stringify(process.env.NX_FLYOUT_SERVICE_URL),
      'process.env.NX_IS_PRE_RELEASE': JSON.stringify(process.env.NX_IS_PRE_RELEASE),
      'process.env.NX_GOOGLE_MAPS_API_KEY': JSON.stringify(process.env.NX_GOOGLE_MAPS_API_KEY),
    })
  );

  return config;
});

2. 检查.env文件加载规则 #

• NX优先加载项目根目录的.env，再加载应用目录下的.env，确保变量定义在正确的文件中
• .env文件中变量无需加export，直接写NX_FLYOUT_SERVICE_URL=https://example.com即可

3. 确认命令行传参格式 #

如果通过命令行临时传递变量，需使用正确格式：

# 开发服务启动
NX_FLYOUT_SERVICE_URL=https://dev.example.com nx serve react-app

# 生产构建
NX_FLYOUT_SERVICE_URL=https://prod.example.com nx build react-app --prod

4. 清除NX缓存 #

缓存可能导致旧环境变量残留，执行以下命令清除：

nx reset

之后重新启动服务或构建应用。

5. 验证环境文件导入路径 #

确保React组件中导入的是正确的环境文件：

import { environment } from './environments/environment';

避免在开发环境误导入environment.prod.ts。

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