必须通过tailwindcss/plugin包裹并用addUtilities注入，直接写CSS或裸导出对象无效；需显式声明variants或respectDefaultVariants:true以支持响应式、hover等变体。
如何在 tailwind.config.js 中添加自定义 utility 类
Tailwind 不支持运行时动态生成 utility，所有自定义类必须在构建时注入配置。核心方式是通过 theme.extend.utilities 或 plugins API 注册新类，后者更灵活、推荐用于带参数的工具（如响应式、变体支持）。
常见错误：直接在 CSS 文件里写 .bg-clip-text 然后期望它响应 hover: 或 md: —— 这类变体不会自动生效，除非你显式注册对应变体逻辑。
- 用
utilities扩展适合无参数、静态样式（如.sr-only类） - 用
addUtilities()+plugin()适合带值的类（如.text-balance或.break-keep） - 若需支持
hover:、focus:、md:等，必须在plugin中调用addVariant或依赖 Tailwind 内置变体机制
编写带值的响应式 utility（例如 text-balance）
想让 text-balance 支持 md:text-balance 和 hover:text-balance，不能只写一个 CSS 声明。必须用插件注册，并告诉 Tailwind “这个类要参与哪些变体”。
示例（tailwind.config.js）：
立即学习“前端免费学习笔记（深入）”；
const plugin = require('tailwindcss/plugin')
module.exports = {
plugins: [
plugin(function ({ addUtilities, variants }) {
const newUtilities = {
'.text-balance': {
'text-wrap': 'balance',
},
}
addUtilities(newUtilities, {
variants: ['responsive', 'hover', 'focus'], // 显式声明支持的变体
})
}),
],
}
注意：variants 选项在 v3.4+ 已被 respectDefaultVariants: true 替代；若用较新版本，应改用 addUtilities(..., { respectDefaultVariants: true })，否则 md: 等断点前缀不生效。
为什么 !important 有时失效？
自定义 utility 的 CSS 优先级默认低于内置类（如 text-red-500），因为 Tailwind 按顺序注入 CSS，插件生成的类在内置类之后，但若你用了 !important 却发现没覆盖成功，大概率是：你写的类名触发了 Tailwind 的“否定逻辑”（如 not-）、或该 utility 被包裹在 @layer components 里导致层级错乱。
- 确保自定义 utility 放在
@layer utilities中（如果手写 CSS），否则可能被压缩或忽略 - 避免在插件中用
!important，改用更高特异性选择器（如.text-balance[data-balance]）更可控 - Tailwind v3.3+ 默认禁用
!important插件行为，需手动开启：important: true或important: '#app'配置项
调试自定义 utility 是否生效
最直接的方式不是看 HTML 是否加了 class，而是检查最终生成的 CSS 文件里有没有对应规则。构建后搜索 text-balance 或你的类名，确认是否出现在 @layer utilities 区域。
容易被忽略的点：
- 修改
tailwind.config.js后必须重启 dev server（npm run dev），热更新不捕获配置变更 - 若使用 PostCSS 插件链（如
postcss-import），确保tailwindcss插件排在靠后位置，否则自定义 utility 可能被提前处理掉 - 类名拼写必须全小写、中划线分隔，
textBalance或text_balance都不会匹配成功
真正麻烦的从来不是写几行配置，而是弄清哪一层（PostCSS、Tailwind、PurgeCSS、浏览器缓存）悄悄吞掉了你的 class。
