addutilities 必须写在 js 插件文件中，不能用于 css；参数需为扁平对象，不支持嵌套媒体查询；主题色须用 theme() 函数获取；动态类应使用 matchutilities；theme() 调用须在插件函数体内。
addUtilities 不能直接写在 CSS 文件里
很多人试过在 @layer utilities 里写 JS 对象结构，结果报错或无效——addUtilities 是 Tailwind 插件 API，只在 Node.js 环境下运行，必须写在 JS 插件文件中，不能混进 CSS。它和 @layer 是两条路：前者生成运行时 CSS 类，后者只是静态样式注入。
addUtilities 的参数必须是纯对象，不支持嵌套媒体查询键
addUtilities 接收一个扁平的对象，每个 key 是类名（如 '.text-gradient'），value 是样式声明对象。你不能把 '@media (min-width: 768px)' 当作 key 直接传进去——Tailwind 会忽略它。
- ✅ 正确做法：用
addUtilities注册基础类，再配合@variants responsive或插件内手动拼响应式类名（如'.md\:text-gradient'） - ❌ 错误写法：
{ '@media (min-width: 768px)': { '.md\:text-gradient': { ... } } } - ⚠️ 注意转义：响应式前缀类名中的冒号要双反斜杠，比如
'md\:text-gradient'，否则 PostCSS 解析失败
主题色引用必须通过 theme() 函数，不能硬编码或用 $ 符号
你在插件里访问颜色、间距等配置，必须调用 theme('colors.blue.500') 这样的函数形式。知识库中提到的 $blue-500 是旧版文档或社区误传，当前版本（v3.4+）不识别这种语法，会返回 undefined，最终生成空字符串或报错。
- ✅ 正确：
background: `linear-gradient(90deg, ${theme('colors.blue.500')}, ${theme('colors.purple.500')})` - ❌ 错误：
background: 'linear-gradient(90deg, $blue-500, $purple-500)' - ? 小技巧：
theme()支持 fallback，比如theme('spacing.8', '2rem')，避免路径不存在时报错
动态类要用 matchUtilities，不是 addUtilities
如果你希望支持像 text-fluid-2xl 这种带参数的类（比如接收任意值生成不同字号），addUtilities 不行——它只适合固定类名+固定样式。这时候必须换 matchUtilities，并配合 theme 中预定义的值表。
- ✅ 正确组合：
matchUtilities({ 'fluid-text': (value) => ({ fontSize: value }) }, { values: theme('fluidSizes') }) - ✅ 对应配置：
theme.extend.fluidSizes = { sm: 'clamp(1rem, 2vw, 1.5rem)' } - ⚠️ 风险点：如果
values是空对象或未定义，matchUtilities不会报错，但类完全不会生成，调试时容易卡住
theme() 调用必须在插件函数体内，不能提前提取到模块顶层；另外，addUtilities 不会自动继承 Tailwind 的变体逻辑（比如 hover、focus），需要显式注册或搭配 addVariant 使用。大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
