tailwind css v4 中添加自定义工具类必须使用 css 层指令：@utility 声明响应式/暗色兼容类，@theme 扩展颜色与断点，@layer components 封装组件类；tailwind.config.js 的 plugins 机制已彻底废弃，js 插件不再生效。
Tailwind CSS v4 中添加自定义工具类，**不再通过 tailwind.config.js 的 plugins 数组注册 JS 插件**——v4 已废弃该机制。所有自定义必须下沉到 CSS 层，用 @utility、@theme 或 @layer 声明，否则类根本不会生成。
用 @utility 定义响应式/暗色模式兼容的工具类
v4 的 @utility 是声明式、CSS-native 的方式，支持嵌套、变体和主题变量引用。它比 v3 的 JS 插件更轻量，也更符合 v4 的编译模型。
-
@utility必须写在@import "tailwindcss"之后的 CSS 文件中（如src/input.css），不能放在 JS 配置里 - 支持直接使用
&:hover、@lg、@dark等变体语法，无需额外配置 - 可调用
theme()函数（仅限在@utility块内），例如color: theme('colors.blue.500') - 避免硬编码值；需要多组类（如
.bg-gradient-1到.bg-gradient-5）时，用@each或重复声明，v4 不支持 JS 循环生成
示例：
如果你了解HTML，CSS和JavaScript，您已经拥有所需的工具开发Android应用程序。本动手本书展示了如何使用这些开源web标准设计和建造，可适应任何Android设备的应用程序 - 无需使用Java。您将学习如何创建一个在您选择的平台的Android友好的网络应用程序，然后转换与自由PhoneGap框架到一个原生的Android应用程序。了解为什么设备无关的移动应用是未来的潮流，并开始构建应用程序，提供更
@utility text-gradient {
background: linear-gradient(90deg, theme('colors.blue.500'), theme('colors.purple.500'));
-webkit-background-clip: text;
-webkit-text-fill-color: transparent;
}
@utility text-gradient:hover {
background: linear-gradient(90deg, theme('colors.indigo.600'), theme('colors.fuchsia.600'));
}
@dark @utility text-gradient {
background: linear-gradient(90deg, theme('colors.cyan.400'), theme('colors.violet.400'));
}
用 @theme 扩展颜色、断点等基础配置
v4 把主题配置完全 CSS 化。@theme 块用于定义全局变量，会被自动映射为工具类前缀（如断点、颜色名），不支持嵌套对象写法。
-
@theme必须写在@import "tailwindcss"之前，否则变量不可用 - 断点声明用
--breakpoint-sm这样的 CSS 变量名，v4 会自动识别并生成sm:变体 - 颜色扩展不走
theme.extend.colors，而是直接定义--color-custom-blue: #3b82f6，然后用custom-blue作为类名片段 - 无效写法：
--color-blue-950不会被识别为blue-950——v4 只认标准命名结构（--color-{name}或--breakpoint-{name}）
示例：
@theme {
--color-custom-blue: #3b82f6;
--breakpoint-xl: 1440px;
}
@import "tailwindcss";
之后即可使用 text-custom-blue 和 xl:grid-cols-4。
用 @layer components 封装组合类（非原子工具类）
如果你要封装的是「多个原子类组合成的语义化组件类」（比如 .btn），而不是新增一个原子能力（如 .sr-only），那就该用 @layer components，不是 @utility。
-
@layer components中的类默认不响应变体（如hover:），需显式加@apply hover:bg-blue-600或用@variant手动扩展 - 它不参与内容扫描优化，所以即使没在 HTML 中出现，也会被输出——适合全局复用的 UI 组件样式
- 不要在
@layer components里写@utility，二者语义不同，混用会导致构建无报错但类未生效 - 优先级低于直接写的原子类，但高于
@layer utilities；若与原子类冲突，原子类胜出
示例：
@layer components {
.btn {
@apply inline-flex items-center px-4 py-2 font-medium rounded-lg transition-colors;
}
.btn-primary {
@apply bg-blue-500 text-white hover:bg-blue-600;
}
}
为什么 tailwind.config.js 里的插件不生效？
v4 彻底移除了对 plugins 数组的支持。如果你还在 tailwind.config.js 里写 plugins: [require('./plugin.js')]，构建会静默忽略，不报错也不生成任何类。
- v4 的 CLI 不再加载或执行 JS 配置文件中的插件逻辑；
tailwind.config.js仅保留极简用途（如指定content路径，虽然通常也不需要） - 已存在的 v3 插件（如
@tailwindcss/forms）在 v4 下必须用对应 v4 版本，且安装后仍需手动引入 CSS（@import "@tailwindcss/forms"），不是靠plugins注册 - 试图用
addUtilities或theme()在 JS 中动态生成类，结果一定是空的——这些函数在 v4 的 JS 配置上下文中已不可用
最常被忽略的一点：v4 的自定义类是否生效，**只取决于它是否出现在最终被 @import 的 CSS 文件中，以及是否符合 @utility/@theme 语法规范**。没有中间态，也没有“插件注册成功但未启用”的模糊地带。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
