vue3+vite使用require 报错❌，一键K.O

提示：本篇只解决关于vue3+vite项目（或老旧vue2升级vue3）出现的require 报错问题

---

---

报错解释

大家在vite项目中使用require 时会出现下面的报错的提示

在vue3+vite构建的项目中，根据官方给出的说明， Vite 使用 ES 模块作为默认的模块系统，并没有内置对 CommonJS （Node.JS 原生方法，用于加载模块/文件/图片）的支持，vue2使用webapck作为构建工具，而Webpack 默认支持 ，Vite 不支持；

或者你像我一样，vue2转vue3的项目，使用了大量的require ，怎么办呢？
看老哈利送你 三把钥匙🔑，助你开启绿洲🌵

---

一、按照官方要求更改（require 🔜 import）[最简单]

这个是最快也是最简单的，建议require 使用量不大的铁铁直接改这个，没必要单独配置

1.1 data参数中类型（vue2）

如果文件类型还是vue2的选项式，参考下面

// 更改前 >>>
	tabList: [{
		title: '快捷入站',
		tips: '包裹入站',
		imgUrl: require('@/static/page/yizhan/icon-enter-station.png'),
	}]
	
// 更改后（导出 Vue2 组件配置对象） <<<
<script>
	// 1. 导入图片资源
	import stationpng from '@/static/page/yizhan/icon-enter-station.png' 
	export default {
	data() {
			return {
			tabList: [{
					title: '快捷入站',
					tips: '包裹入站',
					imgUrl: stationpng, // 定义响应式数据
				}]
			...
			}
// ---------------vue2 转 vue3 -----------------------------

1.2 data参数中类型（vue3）

如果文件类型还是是新的vue3的组合式，参考下面

// 更改后（vue3语法） <<<
// --------------- vue3 ------------------------------------
import { ref } from 'vue';
import stationpng from '@/static/page/yizhan/icon-enter-station.png';

// 用 ref 包裹数组，响应式处理
const tabList = ref([
  {
    title: '快捷入站',
    tips: '包裹入站',
    imgUrl: stationpng,
  }
]);

二、安装（vite-plugin-require插件）[简单兼容性]

快速兼容 require() 函数调用，简单易用，轻量化

1.命令行安装

	// npm 引入
  npm i vite-plugin-require 
  // yarn 引入
  yarn add vite-plugin-require

安装成功

2.声明配置

请在你的 vite.config.js 中 添加配置项

// vite.config.js
import { defineConfig } from 'vite';
import requirePlugin from 'vite-plugin-require';

export default defineConfig({
  plugins: [
    requirePlugin() // 无额外配置，直接启用
  ]
});

如果只是之前 Vue2 代码中用 require 引入图片（如 imgUrl: require(‘@/static/…’)），迁移到 Vue3/Vite 后，用这个插件可以快速兼容，无需手动替换所有 require 为 import。

三、安装（vite-plugin-require-transform三方依赖）[深度兼容性]

注意：这里是用于拓展的第三种方法

为什么这里补充了第三种方法呢，第二种是vite官方给出的极简兼容配置，但是对于老旧的vue2项目迁移到vue3的这种特殊案例，如项目中引入了老的 CommonJS 格式工具库（如自定义 utils.js 用 module.exports 导出），或者代码中存在 exports.default = xxx 等语法，需要用这个插件才能完全兼容，vite-plugin-require 无法处理这类场景。

所以我们就需要引用更为强大的三方依赖包来解决这一问题

全量 CommonJS 转 ESM

1.命令行安装

	// npm 引入
	npm install vite-plugin-require-transform --save-dev
 	// yarn 引入
 	yarn add vite-plugin-require-transform

安装成功

2.声明配置

请在你的 vite.config.js 中 添加配置项

// vite.config.js
import { defineConfig } from 'vite';
import requireTransform from 'vite-plugin-require-transform';

export default defineConfig({
  plugins: [
     requireTransform({
      // 配置需要转换的文件类型（默认 js,jsx,cjs,mjs）
      fileRegex: /\.(js|mjs|cjs|vue)$/,
      // 自定义转换规则（可选）
      transform: (code, id) => {
        // 比如忽略某些文件的转换
        if (id.includes('node_modules')) return code;
        return code;
      }
    })
  ]
});

这个地方需要注意一点，如果你已经在plugins中配置了关键配置，注意先后顺序否则可能会影响应用的构建

两种依赖的补充说明对比

一、核心差异总览表

对比维度	vite-plugin-require	vite-plugin-require-transform
核心定位	快速兼容 require() 函数调用（无其他 CommonJS 语法转换）	完整转换 CommonJS 语法到 ESM（require/module.exports/exports 全支持）
解决的核心问题	项目中零散 require('静态资源') 调用（如图片、JSON），Vite 原生不支持	第三方依赖 / 旧代码是 CommonJS 模块（含 module.exports），需转为 ESM 适配 Vite
转换范围	仅处理 require() 函数（不支持 module.exports/exports）	全面处理 CommonJS 核心语法（require/module.exports/exports.default 等）
使用场景	1. 迁移 Vue2 项目到 Vite，残留 require 引入资源；2. 简单场景临时兼容 require	1. 引入无 ESM 版本的 CommonJS 第三方库；2. 旧项目大量使用 module.exports；3. 动态 require 等复杂语法
配置复杂度	极低（零配置启用）	中等（支持自定义转换规则、忽略文件）
生态兼容性	仅兼容 Vite（专注单一功能）	兼容 Vite/Rollup（基于 @rollup/plugin-commonjs 二次封装，扩展性强）

二、核心功能拆解（附代码示例）

1. vite-plugin-require：极简 require 兼容

核心原理

在 Vite 编译阶段，将代码中 静态路径的 require 调用 直接替换为 ESM 的 import 语法，不处理其他 CommonJS 语法。

代码转换示例

// 原代码（CommonJS，Vue2 中常见）
const img = require('@/static/icon-enter-station.png');

// 插件转换后（ESM，适配 Vite）
import img from '@/static/icon-enter-station.png';

适用场景

• 迁移旧项目时，零散存在 require 引入图片、JSON 等静态资源；
• 无需处理 module.exports，仅需兼容 require 函数调用；
• 追求轻量、无配置的快速兼容方案。

2. vite-plugin-require-transform：全量 CommonJS 转 ESM

核心原理

基于 @rollup/plugin-commonjs 扩展，不仅处理 require，还会将 module.exports/exports 等 完整 CommonJS 语法 转为 ESM 规范，支持动态 require、循环依赖等复杂场景。

代码转换示例

// 原代码（完整 CommonJS 模块）
const utils = require('./utils'); // require 引入
const version = '1.0.0';

// module.exports 导出
module.exports = {
  add: (a, b) => a + b,
  utils,
  version
};

// 插件转换后（ESM 模块）
import utils from './utils'; // 转为 import
const version = '1.0.0';

// 转为 ESM 导出
export const add = (a, b) => a + b;
export { utils, version };
export default { add, utils, version };

适用场景

• 引入的第三方依赖是纯 CommonJS 格式（无 ESM 版本），导致 Vite 报错；
• 旧项目大量使用 module.exports/exports 导出模块，需批量转为 ESM；
• 存在动态 require（如 require(${path}/utils.js)）、exports.__esModule 等复杂语法。

三、选型决策指南（快速选对插件）

需求场景	推荐插件
仅兼容 require('静态路径') 引入资源（如图片）	vite-plugin-require（轻量零配置）
需要兼容 module.exports/exports	vite-plugin-require-transform
引入无 ESM 版本的 CommonJS 第三方库	vite-plugin-require-transform
存在动态 require 等复杂语法	vite-plugin-require-transform
追求极简配置，仅临时兼容少量 require	vite-plugin-require

四、使用注意事项

1. 禁止同时安装两款插件：会导致语法重复转换，出现 import 重复定义、路径解析错误等问题；
2. 优先使用原生 ESM 语法：两款插件均为「兼容方案」，长期来看建议逐步将 require 改为 import，module.exports 改为 export，减少插件依赖；
3. Vite 原生兼容说明：Vite 本身已支持部分 CommonJS 兼容（如引入 node_modules 中的 CommonJS 依赖），但对项目源码中的 require 调用不支持，需插件补充；
4. Vue3 项目适配：如果是 Vue2 迁移 Vue3/Vite，仅图片引入用 require → 选 vite-plugin-require；若存在大量 module.exports 工具库 → 选 vite-plugin-require-transform。

---

总结：Vue3+Vite 遇 require 报错？三把「破局钥匙」让你秒通关！

谁懂啊家人们！从 Vue2 跳进 Vue3+Vite 的坑，第一件事可能就是被 require 报错糊脸——明明在 Webpack 里好好的，到 Vite 这儿直接红波浪警告，仿佛在说「你这老古董语法我不认！」😤

其实核心症结特简单：Vite 天生认准 ES 模块（import/export），对 CommonJS 的 require 是「自带排斥体质」，而 Vue2 时代的老项目、老依赖，偏偏满是这玩意儿。但别怕，这篇文章直接给你备齐「梯度解决方案」，从「零成本手动改」到「插件一键兼容」，按需pick，秒变顺风顺水～

如果你的 require 只是零星出现（比如几个图片引入），直接上手「手动换乘」import——Vue2 选项式 API 改导入、Vue3 组合式 API 配 ref/reactive，几行代码搞定，干净又纯粹，还能顺便优化项目语法；

要是 require 多到像「满天星」，改到手软？那「轻量选手」vite-plugin-require 就是救星！零配置安装启用，直接把静态路径的 require 偷偷转成 import，主打一个「润物细无声」，不用动一行业务代码；

可如果遇到「硬骨头」——老项目里全是 module.exports 工具库、动态 require 语法，甚至第三方依赖只有 CommonJS 版本？那就得上「全能战神」vite-plugin-require-transform，从 require 到 module.exports 全量转 ESM，复杂场景也能拿捏得明明白白～

简单说：少量 require 手动改，中等场景用轻量插件，复杂老项目上全能插件，三者按需选择，再也不用为 require 报错秃头！最后友情提示：插件别叠着装、长期尽量用原生 import，才能让 Vite 跑得又快又稳，告别兼容性烦恼～ 🚀