企业官网建设流程全解析

Vite 配置文件报 This package is ESM only 怎么解决？

【免费下载链接】viteNext generation frontend tooling. It's fast!项目地址: https://gitcode.com/GitHub_Trending/vi/vite

运行vite启动开发服务器或vite build构建时，如果配置文件里引入的某个依赖是 ESM only 包，而配置本身被 Node.js 当作 CommonJS 加载，就会在加载配置阶段失败。Vite 官方 troubleshooting 文档给出了两种报错形态（下面是文档中的示例文本，"foo"和路径在你的实际报错里会替换成真实的依赖名与文件路径）：

Failed to resolve "foo". This package is ESM only but it was tried to load by `require`.

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/dependency.js from /path/to/vite.config.js not supported. Instead change the require of index.js in /path/to/vite.config.js to a dynamic import() which is available in all CommonJS modules.

官方文档对原因的描述是：通过require引入一个 ESM only 包时会触发该错误；在 Node.js <=22 中，ESM 文件默认不能通过require加载。解决办法就是把配置文件转成 ESM，文档推荐两种方式，任选其一。

先确认 Node.js 版本

Vite 要求 Node.js 版本 20.19+、22.12+；部分模板可能要求更高的 Node.js 版本，如果包管理器有提示请按提示升级。确认本地 Node.js 在支持范围内后再按下面步骤修改，否则配置加载行为可能与文档描述不一致。

方式一：在最近的 package.json 中加入"type": "module"

找到离配置文件最近的package.json，在其中加入"type": "module"这一项（加在你现有内容中，不要覆盖整个文件）：

{ "name": "my-app", "type": "module" }

配置完成后重新运行之前报错的命令即可。

方式二：把配置文件重命名为 .mjs / .mts

如果不想影响整个包的模块类型，可以直接改文件扩展名：

• vite.config.js重命名为vite.config.mjs
• vite.config.ts重命名为vite.config.mts

Vite 默认在项目根目录自动解析配置文件，除vite.config.js外还支持其他 JS 和 TS 扩展名，所以重命名后vite命令仍会找到它。如果之前是用vite --config my-config.js显式指定了配置文件（该路径相对于当前工作目录解析），需要把参数同步改成重命名后的文件名。

验证

重新运行之前失败的命令（vite或vite build）：配置文件正常加载、不再出现This package is ESM only或ERR_REQUIRE_ESM报错，且 dev server 能正常启动或构建正常进入产出阶段，即说明修复完成。

其他可行但非官方推荐的路径

troubleshooting 文档同时说明：使用 Node.js 的--experimental-require-module标志、使用 Node.js >22、或其他运行时，可能让这个错误消失，但官方仍推荐把配置转成 ESM。因此前两种方式是默认选择，实验性标志只建议作为临时手段了解。

另外作为背景：从 Vite 7 起 Vite 以 ESM only 方式分发（Vite 8 沿用相同的 Node.js 版本要求），这也是生态中 ESM only 包变多、这类报错出现频率上升的原因。

相关文档：

• Troubleshooting: This package is ESM only
• Configuring Vite
• Installing Vite（Node.js 版本要求说明）

【免费下载链接】viteNext generation frontend tooling. It's fast!项目地址: https://gitcode.com/GitHub_Trending/vi/vite