Tailwind CSS @apply 报错原因及解决方法

Tailwind CSS 的 `@apply` 指令看似便捷，实则高度依赖构建链路的精密配合——它并非原生 CSS 语法，而是 PostCSS 编译阶段的“智能文本替换”，一旦文件未纳入编译流程、路径未被 `content` 正确扫描、作用域隔离缺失 `@reference` 声明，或 `@layer` 使用顺序错乱，就会悄无声息地失效甚至报错；从普通 CSS 文件直写报错、Vue/Svelte 中静默不生效，到生产环境样式突消失，根源往往不是代码写错，而是 PostCSS 配置、路径匹配、作用域控制与层序规则这四重机制的隐性耦合，掌握其底层逻辑才能真正破局。

为什么 @apply 在普通 CSS 文件里直接写就报错

因为 @apply 不是标准 CSS 语法，浏览器和原生构建流程根本不认识它。它只是 Tailwind 的 PostCSS 插件在编译阶段做的“文本替换”——把 @apply bg-blue-500 text-white; 展开成实际的声明块。所以：

• 如果文件没走 PostCSS 流程（比如你随便建了个 style.css 直接 @import 进去），@apply 就会被当成无效规则忽略，控制台不报错但样式不生效
• 如果构建工具（如 Vite）默认跳过了该文件（例如路径不在 src/ 下、后缀不是 .css 或 .postcss），PostCSS 插件压根不会碰它
• Vite 3.0+ 默认对 .css 启用 PostCSS，但如果你用了 css.preprocessor（比如启用了 scss），Vite 可能会绕过 Tailwind 插件，导致 @apply 失效

@apply 报 Cannot apply unknown utility class 怎么查

这个错误说明 PostCSS 虽然运行了，但 Tailwind 没能把类名解析出来。常见原因有：

• tailwind.config.js 里 content 字段没覆盖到当前文件路径，导致类名未被扫描注册（Tailwind v3.3+ 默认只扫描 src/**/*.{html,js,ts,jsx,tsx}）
• 你在 SCSS/Sass 文件里写了 @apply，但 postcss.config.js 没配好链式处理顺序（Sass 编译必须在 PostCSS 之前，否则 @apply 还没被处理就进 Sass 解析器了）
• 用了 CSS Modules 或