如何使用Tailwind CSS插件编写函数来添加自定义CSS实用工具类？

本文共计834个文字，预计阅读时间需要4分钟。

要使用 Tailwind CSS 插件，首先需要安装它。可以使用以下命令：

怎么写一个合法的插件函数

插件必须是导出一个函数的模块，且该函数接收一个上下文对象（含 addUtilities、theme 等），不能直接返回样式对象或调用 addUtilities 顶层。

• 错误写法：module.exports = { '.text-gradient': { ... } } —— Tailwind 不识别纯对象
• 正确结构：用 const plugin = require('tailwindcss/plugin') 包一层，再 module.exports = plugin(...)
• 函数体里才能安全调用 theme('colors.blue.500')；在 module.exports 外层访问会报 theme is not a function
• 如果要用转义类名（比如带斜杠的 .aspect-16/9），得传 e 参数并显式调用 e('16/9')

addUtilities 支持哪些写法

addUtilities 接收一个样式对象或数组，但格式稍有差异：键是类名字符串，值是 CSS 声明对象；媒体查询和深色模式需作为独立键写入，不能嵌套。

• 基础工具类：{ '.sr-only-focusable': { position: 'absolute', clip: 'rect(0 0 0 0)' } }
• 响应式变体要手动展开：'@media (min-width: 768px)': { '.md\:sr-only-focusable': { ... } }（注意双反斜杠转义冒号）
• 深色模式写法：'.dark .dark\:bg-primary': { backgroundColor: theme('colors.primary.600') }
• 不支持嵌套选择器如 &:hover —— 那属于组件范畴，该用 addComponents

为什么 theme() 有时取不到值

theme() 只能读取 tailwind.config.js 中 theme.extend 或默认定义的路径，比如 theme('spacing.4') 有效，但 theme('fluidSizes.xs') 必须先在配置里声明过才不会返回 undefined。

立即学习“Java免费学习笔记（深入）”；

• 常见坑：theme('colors.myBrand.500') 报错？检查配置里是否写了 extend: { colors: { myBrand: { 500: '#...' } } }
• 想动态生成多组类（如所有 aspect-* ），别硬编码，用 Object.entries() 转成数组再传给 addUtilities
• 开发时建议加个 fallback：theme('colors.primary.500', '#3b82f6')，避免主题未定义导致构建失败

matchUtilities 更适合带参数的类

如果你需要像 text-fluid-sm 这样带后缀、对应不同值的类，addUtilities 写起来太啰嗦，该用 matchUtilities —— 它自动处理前缀匹配和值映射。

• 示例：matchUtilities({ 'text-fluid': (value) => ({ fontSize: value }) }, { values: theme('fluidSizes') })
• values 必须是对象（如 { sm: 'clamp(1rem, 2vw, 1.5rem)' }），不能是数组
• 生成的类名是 text-fluid-sm，不是 text-fluid:sm；冒号语法需靠 addVariant 实现
• 性能上比 addUtilities 略重，简单固定类优先选后者

最易被忽略的一点：插件里写的类名，必须出现在 content 配置扫描的文件中，否则 PurgeCSS 会把它删掉——哪怕你已经在 JS 里 document.body.classList.add('text-gradient')，Tailwind 也看不到。