Vite 6 配置 TailwindCSS 出现 "@tailwindcss/vite" 解析错误

问题描述

在升级到 Vite 6 的 React 项目中，按照官方文档配置 TailwindCSS v4 和 DaisyUI v5 后，运行 npm run dev 时出现以下错误：

✘ [ERROR] Failed to resolve "@tailwindcss/vite". This package is ESM only but it was tried to load by `require`. See https://vite.dev/guide/troubleshooting.html#this-package-is-esm-only for more details. [plugin externalize-deps]

这个问题的核心原因是模块系统兼容性问题 - 在 CommonJS (CJS) 环境中尝试加载仅支持 ES 模块 (ESM) 的包。

解决方案

方法一：重命名配置文件（推荐）

将 vite.config.js 重命名为 vite.config.mjs：

bash

mv vite.config.js vite.config.mjs

方法二：在 package.json 中指定模块类型

在 package.json 中添加 "type": "module" 字段：

json

{
  "private": true,
  "type": "module",
  "scripts": {
    // 你的脚本配置
  },
  // 其他配置...
}

问题原因分析

模块系统不兼容

TailwindCSS v4 及许多现代 npm 包现在只支持 ES 模块 (ESM)，而传统的 .js 配置文件默认使用 CommonJS (CJS) 模块系统。

当 Vite 尝试通过 require() (CJS) 加载 @tailwindcss/vite 时，由于该包仅支持 ESM，导致解析失败。

ESM 和 CJS 的主要区别：

ESM：使用 import/export 语法，是现代 JavaScript 的标准模块系统
CJS：使用 require/module.exports，是 Node.js 的传统模块系统

完整配置示例

修改后的 vite.config.mjs 文件：

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [react(), tailwindcss()],
  base: "/",
});

注意事项

升级建议

检查依赖兼容性：升级到 ESM 后，确保所有依赖都支持 ES 模块
逐步迁移：对于大型项目，建议逐步迁移到 ESM
工具链更新：确保构建工具和开发环境都支持 ESM

可能的影响

如果项目中使用了仅支持 CJS 的传统库，切换到 ESM 可能会导致其他兼容性问题。在这种情况下，可能需要寻找替代的现代库或使用兼容层解决方案。

总结

Vite 6 与 TailwindCSS v4 的兼容性问题通常通过将配置文件转换为 ESM 格式即可解决。推荐使用 vite.config.mjs 方案，这是最直接且符合现代 JavaScript 发展趋势的解决方案。

随着生态系统向 ESM 迈进，尽早适配 ES 模块将有助于保持项目的长期可维护性和兼容性。

相关文章

Vite 6 配置 TailwindCSS 出现 "@tailwindcss/vite" 解析错误 ​

问题描述 ​

解决方案 ​

方法一：重命名配置文件（推荐） ​

方法二：在 package.json 中指定模块类型 ​

问题原因分析 ​

完整配置示例 ​

注意事项 ​

总结 ​