使用Tailwind标准工具类时主CSS文件报“无法应用未知工具类”错误

问题描述 #

使用Vite插件、PostCSS插件或CLI构建项目时，在主CSS文件（./src/index.css）中导入TailwindCSS后，在@layer base代码块内使用@apply调用标准工具类，会触发未知工具类错误，导致构建失败。

用户代码示例：

@import url("tailwindcss");

@layer base {
  *,
  ::after,
  ::before,
  ::backdrop,
  ::file-selector-button {
    border-color: var(--color-gray-200, currentColor);
  }

  div {
    scrollbar-color: var(--color-neutral-400) transparent;
  }

  body {
    margin: 0;
    display: flex;
    flex-direction: column;

    @apply bg-slate-50; /* 无法应用未知工具类 `bg-slate-50` */
    /* 此时构建会因严重错误终止 */

    @apply text-neutral-700;
  }

  a {
    @apply text-purple-900 hover:text-purple-700 hover:underline;
  }

  button {
    cursor: pointer;
  }
}

错误提示（已翻译）：

[plugin:@tailwindcss/vite:generate:serve] 无法应用未知工具类 bg-slate-50。你是否在使用CSS模块或类似方案且缺少@reference？

注：官方提示的@reference指令仅适用于CSS模块场景，当前主CSS文件不适用该方案。

解决方案 #

1. 修正TailwindCSS导入语法 #

原代码中@import url("tailwindcss");的导入方式错误，会导致Tailwind无法正确加载工具类。替换为官方推荐的导入方式：

@tailwind base;
@tailwind components;
@tailwind utilities;

或者使用@import的正确写法：

@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

将导入语句放在CSS文件最顶部，确保工具类在@apply执行前已被加载。

2. 检查Tailwind配置文件 #

确保tailwind.config.js中content字段包含了当前CSS文件的路径，让Tailwind能扫描到该文件：

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx,vue}",
    "./src/**/*.css" // 必须包含CSS文件路径
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

3. 确认构建工具配置正确 #

• 如果使用Vite：确保vite.config.js中正确配置了PostCSS，且TailwindCSS插件已加入PostCSS配置。
• 如果使用PostCSS单独配置：检查postcss.config.js中是否包含tailwindcss和autoprefixer插件。

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