cd ..

关于在 CSS 模块中使用 UnoCSS 规则 "@apply" 报错的解决方案

在使用 Unocss 或其他原子化 CSS 框架时，@apply 指令在 CSS 模块中可能会出现报错提示。虽然这些错误不影响实际功能，但对于代码洁癖者来说确实令人困扰。本文将介绍如何解决这些问题。

用 UnoCSS 写样式的时候，你大概见过这种场景：代码明明跑得好好的，浏览器渲染也完全正常，但 VSCode 的编辑器里赫然挂着一条红色波浪线，提示你 @apply 是个”未知规则”。

功能没问题，但那条红线就是碍眼。尤其是当你打开一个文件，满屏都是这种”假错误”的时候，真正的问题反而容易被淹没。

这篇文章就来彻底解决这个烦人的问题。

问题一：@apply 指令报错

在 <style> 标签或者 .css 文件中使用 @apply 时，编辑器会显示错误提示：

Uncoss @apply 错误提示

这个报错的根源在于 VSCode 内置的 CSS 语言服务不认识 @apply 这个指令 — 它不是标准 CSS 规范的一部分，所以编辑器理所当然地认为你写错了。

解决方案

issues/2401

解决思路很直接：告诉 VSCode “这些指令是合法的，别报错了”。具体分两步：

  1. 在 VSCode 的 settings.json 中添加以下配置：
{
  "css.customData": [".vscode/unocss.json"]
}
  1. 在项目的 .vscode 目录中创建 unocss.json 文件：
{
  "version": 1.1,
  "atDirectives": [
    {
      "name": "@apply"
    },
    {
      "name": "@screen"
    }
  ]
}

这样配置后，VSCode 的 CSS 语言服务会把 @apply 和 @screen 当作已知指令，红线就消失了。

问题二：自定义规则报错

以为大功告成了？别急。上面的方案只解决了 @apply 指令本身的报错，如果你在 @apply 后面用了 UnoCSS 的自定义规则（比如你在 uno.config.ts 里自己定义的 shortcuts），编辑器可能还是会抱怨：

自定义规则报错

这是因为 VSCode 虽然认识 @apply 了，但它不认识你后面跟的那些自定义类名。

解决方案

这时候就需要换一种写法了。根据 @unocss/transformer-directives 的文档，UnoCSS 提供了基于 CSS 变量的替代语法，完全绕开了 @apply：

.custom-class {
  --uno: text-center mt-4;
}

用 --uno: 作为 CSS 自定义属性的前缀，后面直接写工具类名。因为 CSS 自定义属性本身就是合法的 CSS 语法，编辑器不会对它报任何错。这个方案可以说是釜底抽薪。

UnoCSS 别名使用

UnoCSS 实际上提供了好几个等价的前缀可以用：

  • --un-apply:
  • --uno-apply:
  • --uno:
  • --un:

UnoCSS 别名

虽然选择很多，但我的建议是在项目中统一使用 --uno:。理由很简单：它最短、最好记，而且团队协作的时候保持一致性比什么都重要。

回顾

处理这类开发体验问题看似不重要，但干净的编辑器环境真的能提升效率 — 当你看到红线就知道是真的出了问题，而不是要在脑子里过滤”哪些是假报错”。总结一下要点：

  1. 通过配置 VSCode，可以消除 @apply 指令的错误提示
  2. 对于自定义规则，使用 —uno: 前缀代替 @apply
  3. 为保持一致性，可以统一使用 —uno: 前缀处理所有规则

把这两个配置做好，UnoCSS 的开发体验就顺畅多了。