React Vite集成Tailwind CSS v4时@apply指令报错求助

问题背景 #

使用React + Vite + Tailwind CSS ^4.1.4 + CSS Modules开发时，在CSS Modules文件中编写如下代码：

.editor {
  @apply max-w-3xl mx-auto my-8 p-6 bg-white rounded-lg shadow-md;
}

运行时触发错误：

[plugin:@tailwindcss/vite:generate:serve] Cannot apply unknown utility class: max-w-3xl

尝试添加@reference "main.css";后，仍出现类似错误：

[plugin:@tailwindcss/vite:generate:serve] Cannot apply unknown utility class: group

现有解决方案多针对Tailwind旧版本，官方文档未明确说明该场景下@apply的用法，Vue项目中的适配方式无法直接复用。

解决方案 #

Tailwind CSS v4采用全新的CSS-in-JS架构，静态CSS文件中的@apply不再自动识别工具类，需按以下方式调整：

1. 配置Tailwind启用CSS Modules支持 #

确保tailwind.config.js中开启CSS Modules支持：

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  plugins: [],
  cssModules: true,
}

2. 在CSS Modules中显式导入Tailwind工具类 #

在使用@apply的CSS Modules文件顶部，添加@tailwind utilities导入所有工具类：

@tailwind utilities;

.editor {
  @apply max-w-3xl mx-auto my-8 p-6 bg-white rounded-lg shadow-md;
}

或使用@layer utilities包裹自定义类，让Tailwind自动处理：

@layer utilities {
  .editor {
    @apply max-w-3xl mx-auto my-8 p-6 bg-white rounded-lg shadow-md;
  }
}

3. 推荐方案：使用类名组合函数替代@apply #

React项目更贴合Tailwind v4的设计理念，推荐使用tailwind-variants提供的cx函数组合类名：

• 安装依赖：

npm install tailwind-variants

• 在组件中使用：

import { cx } from 'tailwind-variants';

function Editor() {
  return (
    <div className={cx('max-w-3xl mx-auto my-8 p-6 bg-white rounded-lg shadow-md')}>
      {/* 组件内容 */}
    </div>
  );
}

export default Editor;

4. 移除无效的@reference语句 #

@reference "main.css"是Vue项目中的特定用法，在React + Tailwind v4环境下无意义，直接移除即可。

原因说明 #

Tailwind CSS v4彻底重构了底层实现，从PostCSS驱动转为CSS-in-JS驱动，静态CSS文件中的@apply无法自动关联Tailwind工具类，必须显式导入或通过@layer声明；而React项目使用类名组合函数，更符合v4的设计思路，也能避免CSS Modules的兼容问题。

内容的提问来源于stack exchange，提问作者Mounir Habbas