shadcn-admin 项目中的 Tailwind CSS 配置问题解析与解决方案

在基于 React 和 Tailwind CSS 构建的 shadcn-admin 项目中，开发者可能会遇到一个与 Tailwind CSS 配置文件相关的构建错误。这个问题主要出现在使用较新版本的 Node.js 时，特别是 Node.js 23.3.0 及以上版本。

问题现象

当开发者执行构建命令时，系统会报出以下错误信息：

ExperimentalWarning: CommonJS module .../tailwindcss/lib/lib/load-config.js is loading ES Module .../tailwind.config.js using require()
ReferenceError: require is not defined

这个错误表明系统尝试使用 CommonJS 的 require() 方法来加载一个 ES 模块格式的配置文件，这在 Node.js 的新版本中不再被支持。

问题根源

这个问题的根本原因在于 Node.js 23.3.0 对模块系统的处理方式发生了变化。新版本的 Node.js 更严格地区分了 CommonJS 和 ES 模块系统，不再允许混用这两种模块加载方式。

具体到 shadcn-admin 项目中，Tailwind CSS 的配置文件 tailwind.config.js 使用了 ES 模块的导出方式（export default），但同时又在其中使用了 CommonJS 的 require() 方法来加载 tailwindcss-animate 插件，这就导致了模块系统冲突。

解决方案

针对这个问题，开发者可以采用以下两种解决方案：

方案一：使用 ES 模块的导入语法

修改 tailwind.config.js 文件，使用 ES 模块的 import 语法来引入 tailwindcss-animate 插件：

import tailwindCssAnimate from 'tailwindcss-animate'

export default {
  // 其他配置...
  plugins: [tailwindCssAnimate],
}

这种方案完全采用 ES 模块规范，是最符合现代 JavaScript 开发实践的解决方案。

方案二：将配置文件改为 CommonJS 格式

将 tailwind.config.js 重命名为 tailwind.config.cjs，并保持使用 require() 语法：

module.exports = {
  // 其他配置...
  plugins: [require('tailwindcss-animate')],
}

这种方案向后兼容性更好，特别适合需要在多种 Node.js 版本环境下运行的项目。

最佳实践建议

1. 版本兼容性：如果项目需要支持多种 Node.js 版本，建议采用方案二，使用 .cjs 扩展名明确表明这是 CommonJS 模块。

2. 未来兼容性：如果项目主要面向现代 JavaScript 环境，建议采用方案一，完全使用 ES 模块语法，这更符合未来的发展趋势。

3. 团队协作：在团队开发环境中，建议在项目文档中明确说明所使用的模块系统，并在 .gitignore 或 .npmrc 中指定 Node.js 版本要求，以避免开发环境不一致导致的问题。

通过理解这个问题的本质并选择合适的解决方案，开发者可以确保 shadcn-admin 项目在不同 Node.js 版本下都能顺利构建和运行。