React 18 + Vite 5生产环境报错：Uncaught ReferenceError: require is not defined

核心原因 #

生产构建后的代码包含Node.js专属的require语法，而浏览器环境不支持该语法，需从代码、依赖、配置三方面排查修复。

具体解决步骤 #

• 替换代码中的require调用
  若项目中有手写的require()，全部改为ES模块的import或动态import()语法。例如：

  // 原代码
  const utils = require('./utils')
  // 修改后
  import utils from './utils'
  
  // 动态加载场景
  // 原代码
  const component = require('./Component')
  // 修改后
  import('./Component').then(module => {
    // 使用模块
  })
  

• 配置Vite转译CommonJS依赖
  部分第三方依赖为CommonJS格式，需在vite.config.js中强制转译：

  import { defineConfig } from 'vite'
  import react from '@vitejs/plugin-react'
  
  export default defineConfig({
    plugins: [react()],
    optimizeDeps: {
      esbuildOptions: {
        target: 'es2020'
      }
    },
    build: {
      commonjsOptions: {
        include: [/node_modules/]
      },
      target: 'es2020'
    }
  })
  

• 移除/替换Node.js专属模块
  若项目引入了fs、path等Node.js内置模块，需替换为浏览器兼容方案：

  • 路径处理：安装path-browserify，并在vite.config.js配置别名

    resolve: {
      alias: {
        'path': 'path-browserify'
      }
    }
    

  • 文件操作：改用浏览器File API替代Node.js的fs模块

• 确认package.json模块类型
  确保package.json中存在"type": "module"字段，强制项目以ES模块模式运行：

  {
    "type": "module",
    // ...其他配置
  }
  

• 清理缓存重新构建
  删除Vite缓存目录后重新构建：

  # Linux/macOS
  rm -rf node_modules/.vite
  # Windows
  rd /s /q node_modules\.vite
  
  npm run build
  

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