React Uncaught ReferenceError: process is not defined 解决方法

WARNING

本文最后更新于 2025年5月8日，基于 React 18+ 和现代构建工具的最新实践

问题概述

在 React 开发中，很多开发者会遇到 Uncaught ReferenceError: process is not defined 错误。这个错误通常在以下情况出现：

• 使用 process.env 访问环境变量时
• 热重载（Hot Reload）过程中
• 项目依赖的某些包尝试访问 Node.js 的 process 对象

错误可能表现为：

Uncaught ReferenceError: process is not defined
    at Object.4043 (<anonymous>:2:13168)
    at r (<anonymous>:2:306599)
    // ... 更多调用栈信息

根本原因

这个问题的根本原因是 react-error-overlay 包（react-scripts 的依赖）在版本 6.0.10 中引入了对 Webpack 5 的支持，但这与 react-scripts v4 不兼容。浏览器环境中本来不存在 Node.js 的 process 对象，但在某些情况下代码试图访问它。

解决方案

根据不同的项目配置，有多种解决方案可供选择：

方法一：使用包版本覆盖（推荐）

使用 Yarn

在 package.json 中添加 resolutions 字段：

{
  "resolutions": {
    "react-error-overlay": "6.0.9"
  }
}

对于 Yarn Workspaces，需要在根 package.json 中添加此配置。

使用 npm (v8.3.0+)

{
  "overrides": {
    "react-error-overlay": "6.0.9"
  }
}

使用 npm (v8.3.0 以下版本)

需要先安装 npm-force-resolutions，然后在 package.json 中添加：

{
  "scripts": {
    "preinstall": "npx npm-force-resolutions"
  },
  "resolutions": {
    "react-error-overlay": "6.0.9"
  }
}

完成后删除 node_modules 和锁文件，重新安装依赖。

方法二：升级 react-scripts

升级到 react-scripts v5.0.0+ 可以解决此问题：

{
  "dependencies": {
    "react-scripts": "^5.0.0"
  }
}

方法三：Webpack 配置解决方案

使用 craco

// craco.config.js
const webpack = require('webpack');

module.exports = {
  webpack: {
    plugins: {
      add: [
        new webpack.DefinePlugin({
          'process.env': JSON.stringify(process.env)
        })
      ]
    }
  }
};

使用 customize-cra

// config-overrides.js
const webpack = require('webpack');
const { override, addWebpackPlugin } = require('customize-cra');

module.exports = override(
  addWebpackPlugin(
    new webpack.DefinePlugin({
      'process.env': {}
    })
  )
);

手动配置 Webpack

// webpack.config.js
const webpack = require('webpack');

module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      'process.env': JSON.stringify(process.env)
    })
  ]
};

方法四：Vite 项目的特殊处理

Vite 用户请注意

Vite 使用 import.meta.env 而不是 process.env

环境变量命名

在 .env 文件中，变量必须以 VITE_ 开头：

VITE_API_URL=http://localhost:8080/api/v1
VITE_API_KEY=your_api_key_here

代码中使用方式

// 正确的方式
const API_URL = import.meta.env.VITE_API_URL;
const API_KEY = import.meta.env.VITE_API_KEY;

// 错误的方式（会导致错误）
const API_URL = process.env.VITE_API_URL;

Vite 配置

// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  // 其他配置...
  define: {
    // 如果需要兼容旧代码，可以添加这个配置
    'process.env': {}
  }
})

方法五：其他实用技巧

处理第三方依赖

如果错误来自第三方依赖（如 jsonwebtoken），可以添加 process 的浏览器 polyfill：

// webpack.config.js
const webpack = require('webpack');

module.exports = {
  resolve: {
    alias: {
      process: "process/browser"
    },
  },
  plugins: [
    new webpack.ProvidePlugin({
      process: 'process/browser',
    }),
  ],
};

然后安装所需依赖：

npm install --save-dev process

条件访问操作符问题

避免在 process.env 上使用可选链操作符：

// 可能有问题
const value = process?.env?.MY_VAR;

// 推荐方式
const value = process.env.MY_VAR;

常见问题排查

1. 检查环境变量前缀

   • Create React App: REACT_APP_
   • Vite: VITE_

2. 确认构建工具

   • 确认项目使用的是 Webpack 还是 Vite
   • 检查 package.json 中的 scripts 和依赖

3. 清理缓存

   rm -rf node_modules
   rm package-lock.json # 或 yarn.lock
   npm cache clean --force
   npm install

总结

Uncaught ReferenceError: process is not defined 错误通常由以下原因引起：

1. react-error-overlay 版本兼容性问题
2. 错误地在浏览器环境中使用 Node.js 的 process 对象
3. Vite 项目中错误地使用 process.env 而不是 import.meta.env

根据项目情况选择合适的解决方案，大多数情况下使用包版本覆盖或升级构建工具可以解决问题。

最佳实践

• 使用适合你构建工具的环境变量访问方式
• 保持依赖更新并注意版本兼容性
• 定期清理项目缓存和锁文件

如果问题仍然存在，建议查看项目特定的构建工具文档，或提供更多错误详细信息以获取针对性帮助。