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

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

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

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

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

问题一：@apply 指令报错

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

[!NOTE] 这个报错的根源在于 VSCode 内置的 CSS 语言服务不认识 @apply 这个指令——它不是标准 CSS 规范的一部分，所以编辑器理所当然地认为你写错了。实际运行不受影响，因为 UnoCSS 的 transformer 会在构建阶段处理掉它。

严格来说，@apply 并非标准 CSS 规范的一部分¹。

解决方案

issues/2401

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

1. 在 VSCode 的 settings.json 中添加以下配置：

{
  "css.customData": [".vscode/unocss.json"]
}

2. 在项目的 .vscode 目录中创建 unocss.json 文件：

{
  "version": 1.1,
  "atDirectives": [
    {
      "name": "@apply"
    },
    {
      "name": "@screen"
    }
  ]
}

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

[!TIP] 把这两个文件提交到 Git 仓库里，团队成员拉取代码后就能自动生效，不用每个人单独配置。

问题二：自定义规则报错

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

[!WARNING] 这种报错同样不影响运行，但会干扰你判断代码是否真的有问题。特别是用了大量 shortcuts 的项目，满屏警告简直让人崩溃。

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

解决方案

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

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

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

三种写法怎么选

实际开发中，你有三种方式在 CSS 中复用 UnoCSS 的工具类，各有适用场景：

写法	示例	编辑器报错	适用场景
@apply	@apply text-center mt-4;	需要额外配置才能消除	熟悉 Tailwind 的团队，习惯迁移
--uno:	--uno: text-center mt-4;	无报错	推荐日常使用，兼容性最好
直接写 class	class="text-center mt-4"	无报错	简单场景，不需要抽取为 CSS 类

我的建议是：能直接写 class 就直接写，需要抽取复用时统一用 --uno:。@apply 除非团队有历史包袱，否则没必要用。

[!TIP] --uno: 写法需要安装 @unocss/transformer-directives 并在 uno.config.ts 中配置 transformers: [transformerDirectives()]。如果你用的是 unocss 完整包，这个 transformer 已经内置了。

UnoCSS 别名使用

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

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

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

回顾

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

1. 通过配置 .vscode/unocss.json，可以消除 @apply 指令的错误提示
2. 对于自定义规则的报错，使用 --uno: 前缀代替 @apply
3. 日常开发推荐 --uno: 写法，兼顾编辑器兼容性和代码复用

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

Footnotes

1. @apply 最初由 Tailwind CSS 引入，用于在 CSS 中复用工具类。它曾作为 CSS @apply 规则提案 被提交到 W3C，但该提案已被废弃。目前 @apply 是各原子化 CSS 框架自行实现的非标准指令，由构建工具在编译阶段处理。 ↩