addUtilities 是唯一安全注入自定义通用类的 API；因其支持 Tailwind 的响应式、深色模式等特性，而手写 CSS 会被按需生成机制忽略，且裸导出或裸函数会破坏构建流程。
addUtilities 是唯一安全注入自定义通用类的 API，其他方式（如直接写 CSS、裸对象导出）要么不生效，要么破坏构建流程。
为什么不能直接在 CSS 里写 .my-class { ... }？
Tailwind 的按需生成机制只扫描 content 路径中出现的类名字符串。你在 CSS 文件里手写 .my-class，但 HTML 或模板里没出现这个类名，它就不会被打包进最终 CSS；即使写了，也绕过了 Tailwind 的响应式、深色模式、变体（hover / focus）等能力支持。
如何用 plugin + addUtilities 正确添加工具类？
必须用 tailwindcss/plugin 包裹函数，否则 addUtilities 和 theme() 不可用，构建会报错：
- ❌ 错误：直接导出对象
module.exports = { '.sr-only': { position: 'absolute' } } - ❌ 错误：裸函数
module.exports = ({ addUtilities }) => { addUtilities(...) } - ✅ 正确：
const plugin = require('tailwindcss/plugin'); module.exports = plugin(({ addUtilities, theme }) => { addUtilities({ '.sr-only': { position: 'absolute', clip: 'rect(0 0 0 0)' } }) })
注意：addUtilities 只接受扁平样式对象，不支持 &:hover 或嵌套结构——这类需求该用 addComponents。
怎么让自定义类支持响应式和 dark 模式？
响应式和深色模式不会自动继承，必须手动展开：
立即学习“前端免费学习笔记（深入）”；
- 响应式要写完整媒体查询键：
'@media (min-width: 768px)': { '.md\:sr-only': { ... } }（冒号前双反斜杠转义） - 深色模式需显式组合选择器：
'.dark .dark\:bg-brand': { backgroundColor: theme('colors.brand.500') } -
theme()只能读取theme.extend中已声明的路径，比如extend: { colors: { brand: { 500: '#0ea5e9' } } }，否则返回undefined
需要动态参数（如 text-2xl、aspect-16/9）时怎么办？
硬编码所有组合不可维护，改用 matchUtilities：
- 匹配正则，提取值：
/^text-([\d.]+)rem$/→ 提取2.5 - 传入
e函数处理任意值：matchUtilities({ 'text-fluid': (value) => ({ fontSize: e(value) }) }, { values: { sm: '0.875rem', lg: '1.125rem' }, supportsVariants: true }) -
supportsVariants: true才能让sm:text-fluid-sm这类写法生效
真正容易被忽略的是：插件加完后，content 数组必须覆盖所有使用该类的文件路径，否则类根本不会生成——哪怕配置全对，漏了 ./src/components/**/*.vue，class="scrollbar-hide" 就是白写。
