直接写 .my-utility { } 不起作用，因 Tailwind 按需生成机制仅扫描 content 路径下模板中出现的类名字符串，硬写 CSS 不被识别且不支持响应式、dark 等变体。
必须用 tailwindcss/plugin 包裹，配合 addUtilities 注入，手写 CSS 或裸导出对象一律不生效。
为什么直接写 .my-utility { } 不起作用？
Tailwind 的按需生成机制只扫描 content 路径下模板中出现的类名字符串。你在 CSS 文件里硬写 .text-gradient，但 HTML 里没出现这个字符串，它根本不会进最终 CSS；即使进了，也绕过了响应式、hover、dark: 等所有变体支持。
常见错误包括：
- 在
src/index.css里直接写.sr-only { position: absolute; } - 在
tailwind.config.js中module.exports = { '.my-class': { color: 'red' } } - 裸函数导出：
module.exports = ({ addUtilities }) => { addUtilities(...) }（缺少plugin包裹）
正确写法：用 plugin + addUtilities
插件必须通过 tailwindcss/plugin 创建，且 addUtilities 只接受扁平样式对象（不能嵌套 &:hover 或媒体查询）。
立即学习“前端免费学习笔记（深入）”；
示例：添加一个渐变文字工具类
const plugin = require('tailwindcss/plugin')
<p>module.exports = plugin(function({ addUtilities, theme }) {
addUtilities({
'.text-gradient': {
background: <code>linear-gradient(90deg, ${theme('colors.blue.500')}, ${theme('colors.purple.500')})</code>,
'-webkit-background-clip': 'text',
'-webkit-text-fill-color': 'transparent',
}
})
})
注意：
-
theme()只能读取theme.extend中已声明的路径，比如extend: { colors: { blue: { 500: '#3b82f6' } } } - 类名含斜杠或冒号（如
.aspect-16/9）必须用e()转义：[`.aspect-${e('16/9')}`] - 该插件必须显式加入
tailwind.config.js的plugins数组，否则静默忽略
如何让自定义工具类支持 md:、dark: 等变体？
这些前缀不会自动继承，必须手动展开。Tailwind 不会帮你把 .text-gradient 自动变成 .md:text-gradient 或 .dark:text-gradient。
正确做法是显式写出带前缀的键：
addUtilities({
'.text-gradient': { /* ... */ },
'@media (min-width: 768px)': {
'.md\:text-gradient': { /* ... */ }
},
'.dark .dark\:text-gradient': {
background: `linear-gradient(90deg, ${theme('colors.indigo.400')}, ${theme('colors.violet.500')})`,
}
})
要点：
- 媒体查询键要用单引号包裹，冒号需双反斜杠转义：
'.md\:text-gradient' - 深色模式要写完整选择器：
'.dark .dark\:text-gradient'，不能只写'.dark\:text-gradient' - 如果需要大量响应式组合，考虑改用
matchUtilities并设置supportsVariants: true
content 配置漏掉路径，类就根本不会生成
哪怕插件写得完全正确、plugins 数组也注册了，只要 tailwind.config.js 的 content 数组没覆盖到使用该类的文件（比如 ./src/**/*.{html,js,svelte,ts}），这个类名就不会被扫描到，最终 CSS 里压根没有它。
最容易被忽略的是：
- 新增插件后忘了检查
content是否包含新组件所在目录（如./src/components/**/*.{svelte,ts}） - 用了 Vite + Svelte，但
content没包含.svelte后缀 - 路径用了相对路径但实际项目结构更深，导致 glob 不匹配
