React Vite使用overlay-navbar时报Dynamic require不支持错误

基于Vite构建的React项目中使用overlay-navbar组件时，程序抛出未捕获错误，核心报错与调用堆栈如下：

Uncaught Error: Dynamic require of "C:/Users/AJAY MAURYA/OneDrive/Desktop/React/E-commerce -1/frontend/node_modules/overlay-navbar/dist/lib/ReactNavbar.min.css" is not supported
__require chunk-Q7D65HC4.js:12
js ReactNavbar.js:14
__require2 chunk-Q7D65HC4.js:18
js index.js:13
__require2 chunk-Q7D65HC4.js:18
 overlay-navbar:1

报错指向组件包内ReactNavbar.min.css的动态require操作不受支持，调用链路覆盖构建生成的chunk文件、overlay-navbar组件源码、项目入口文件。

• Vite 天然基于ES Module规范做模块解析，而overlay-navbar是按CommonJS规范打包的老旧组件包，包内使用CommonJS的require()语法引入CSS静态资源。
• Vite 默认的CommonJS转换逻辑不支持CJS模块中对CSS等非JS资源的动态require调用，直接解析时就会抛出该错误。

• 顺着调用堆栈定位错误触发点：从报错栈可以看到错误并非来自业务代码，而是第三方依赖包内部的资源引入逻辑，优先排查依赖与构建工具的规范兼容问题。
• 核对依赖包源码：打开node_modules/overlay-navbar/dist/lib/ReactNavbar.js文件，确认第14行确实存在require('./ReactNavbar.min.css')的写法，验证是包内CJS风格资源引入导致的兼容问题。
• 检查Vite配置：确认配置中未开启CJS混合模块转换、未对该依赖做预构建适配，进一步锁定问题来源。

按实现成本从低到高排序：

方案1：手动引入样式+调整Vite预构建配置（优先尝试） #

跳过包内的CSS require逻辑，手动在业务侧引入样式，同时让Vite正确处理包的CJS格式：

1. 在项目入口文件（通常是main.jsx/main.tsx）或使用导航栏的页面文件顶部，先引入组件CSS，再引入组件本身：

// 手动引入组件样式，跳过包内的require逻辑
import 'overlay-navbar/dist/lib/ReactNavbar.min.css'
// 引入组件
import { ReactNavbar } from 'overlay-navbar'

2. 修改项目根目录的vite.config.js配置，开启CJS混合模块转换，将该依赖加入预构建列表：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  optimizeDeps: {
    // 预构建overlay-navbar，提前转成ESM格式
    include: ['overlay-navbar']
  },
  build: {
    commonjsOptions: {
      // 支持混合ES/CJS模块的转换
      transformMixedEsModules: true
    }
  }
})

3. 删除项目根目录下的node_modules/.vite缓存文件夹，重启Vite开发服务即可生效。

方案2：添加CJS兼容插件处理资源require #

如果方案1仍未解决问题，通过Vite插件补全CommonJS模块下静态资源require的解析能力：

1. 安装开发依赖：

npm install @originjs/vite-plugin-commonjs -D

2. 修改vite.config.js，引入插件并指定要处理的依赖：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { viteCommonjs } from '@originjs/vite-plugin-commonjs'

export default defineConfig({
  plugins: [
    react(),
    viteCommonjs({
      include: ['overlay-navbar']
    })
  ]
})

3. 同样清除.vite缓存后重启服务。

方案3：替换适配ESM的同类组件（长期维护推荐） #

overlay-navbar已经长期没有版本更新，未做ESM/Vite生态适配，后续可能还会出现其他兼容问题。长期维护的项目可以直接替换为原生支持ESM、适配Vite的导航栏组件，从根源避免这类兼容问题。

内容的提问来源于stack exchange，提问作者Ajay Kumar Maurya