Tailwind CSS @utility 指令

在上一节中，我们学习了如何使用 @layer 来定义自定义工具类。虽然那种方式已经很强大，但在 Tailwind CSS v4 中，官方为了进一步简化开发流程，推出了专门的 @utility 指令。

如果我们只需要定义一个单一功能的工具类（比如特殊的文字阴影或裁剪路径），使用 @utility 是目前最推荐、最规范的做法。

Tailwind CSS @utility 语法

在 Tailwind CSS v4 中，@utility 指令专门用于注册自定义工具类。它会被引擎自动识别并放置在正确的 “工具层” 中。

语法：

@utility 工具类名称 { ... }

说明：

@utility 指令本质上是 @layer utilities 的语法糖，但更加语义化。在 @utility 后面写类名时，不需要像传统 CSS 那样加点（.）。

此外，@utility 会自动支持修饰符，这也是它最强大的地方。比如定义了 @utility text-glowing，Tailwind CSS 会自动生成 hover:text-glowing、md:text-glowing 以及 dark:text-glowing 等所有变体，而不需要写任何额外代码。

Tailwind CSS @utility 示例

接下来，我们通过一个简单的例子来讲解一下 Tailwind CSS 中的 @utility 指令是如何使用的。

示例：使用 @utility

运行代码

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title></title>
    <script src="https://unpkg.com/@tailwindcss/browser@4"></script>
    <style type="text/tailwindcss">
        @theme {
            --color-lvye: #19b694;
        }
        /* 使用 @utility 定义一个发光工具类 */
        @utility text-glowing {
            text-shadow: 0 0 15px rgba(25, 182, 148, 0.8);
        }
        /* 使用 @utility 定义一个特殊的底部边框渐变 */
        @utility border-b-gradient {
            border-bottom-width: 4px;
            border-image: linear-gradient(to right, #19b694, #3b82f6) 1;
        }
    </style>
</head>
<body class="p-10 bg-gray-900 flex flex-col items-center justify-center min-h-screen">
    <div class="max-w-md text-center">
        <h1 class="text-5xl font-black text-white transition-all duration-300 hover:text-glowing cursor-pointer">
            绿叶网
        </h1>
        <p class="mt-6 text-gray-400 leading-relaxed">
            专注于教程的易懂性，让完全 0 基础的小白也能更快上手。
        </p>
        <div class="mt-8 inline-block text-lvye font-bold border-b-gradient pb-2">
            探索更多精品教程
        </div>
    </div>
</body>
</html>

页面效果如下图所示。

Tailwind CSS @utility 示例

分析：

在这个例子中，我们使用 @utility 指令定义了两个自定义工具类：

text-glowing：由于 Tailwind CSS 默认没有提供类似 text-shadow 的类名，我们使用 @utility 指令扩展了它。然后，在 HTML 中我们直接写 hover:text-glowing 就能生效了。
border-b-gradient：这种涉及 border-image 的复杂样式，如果用传统的原子类组合会非常臃肿，甚至做不到。通过使用 @utility 指令封装后，我们在 HTML 中只需要一个简洁的类名就能实现高级感十足的渐变边框。

常见问题

1. 既然有了 @utility，我还需要使用 @layer utilities 吗？

对于绝大多数自定义 “单一功能” 的类名，推荐优先使用 @utility。只有当你需要在一个代码块里同时定义很多个复杂的 CSS 规则，或者需要利用旧版的某些嵌套特性时，才考虑使用 @layer utilities。

2. 为什么我在 @utility 里编写的类名不生效呢？

你应该检查一下 HTML 标签是否正确引用了该类名。此外，由于 Tailwind CSS v4 采用了按需编译机制，如果你在 JavaScript 动态拼接类名，确保你的扫描路径包含了这些 JavaScript 文件。