怎样在Tailwind CSS中配置并使用自定义变量？

Tailwind 中 CSS 变量不能直接用于配置文件，需用 @theme（v4+）或 @layer utilities + :root 实现；静态色写 config，动态色走 CSS 层级，混用会导致变体缺失、NaN 颜色等问题。

tailwind.config.js 里不能直接写 var(--x)

写了就会崩——不是语法错，是 Tailwind 构建时根本没法解析 var(--primary) 这种字符串。它要生成 bg-primary-500、hover:bg-primary 这些变体，就得把颜色拆成 r/g/b 去算暗化、透明度叠加。而 var(--primary) 在 JS 配置里只是个普通字符串，parseColor() 拿不到真实值，直接报 Cannot read property 'r' of undefined。

常见现象：bg-primary 能出来，但 bg-primary-600 完全不生成；text-primary/50 渲染成 color: rgb(NaN)；深色模式下 dark:bg-primary 无效。

• 想复用固定色值？直接写 brand: '#1677FF'，所有变体自动可用
• 变量名拼错、没在 :root 定义、或用了未声明的 CSS 变量，Tailwind 不报错，只默默产出非法 CSS
• 哪怕写成 rgb(var(--tw-primary))，Tailwind 也不校验该变量是否存在，运行时出问题极难定位

@theme 规则是 v4+ 最简路径

v4 开始原生支持 @theme at-rule，不用配 config、不用手写 utility，变量定义和类名生成一步到位。

在主 CSS 文件（如 src/index.css）里写：

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

@import "tailwindcss";@theme {  --color-primary: #1677FF;  --color-error: #ef4444;  --radius-card: 8px;}

保存后就能直接用 text-primary、bg-error、rounded-card，Tailwind 自动绑定到对应属性。

• 命名必须带前缀：颜色用 --color-*，圆角用 --radius-*，字体大小用 --text-*，否则不生效
• @theme 必须放在 @import "tailwindcss" 之后，且不能嵌套在其他规则里
• 变量值支持 HEX、RGB、HSL，也支持函数如 linear-gradient(...)，但不要写 var(--x) 套娃

@layer utilities + :root 是运行时切换唯一可靠方式

用户点按钮换主题、响应 prefers-color-scheme、JS 动态调用 document.documentElement.style.setProperty('--primary', '#...') —— 这些场景只能靠 CSS 层级绑定，绕过 Tailwind 颜色系统。

在 CSS 文件里写：

@layer utilities {  .text-brand { @apply text-[var(--color-brand)]; }  .bg-brand { @apply bg-[var(--color-brand)]; }  .border-brand { @apply border-[var(--color-brand)]; }}

同时确保全局已定义：

:root {  --color-brand: #1677FF;}@media (prefers-color-scheme: dark) {  :root {    --color-brand: #2563eb;  }}

• @apply text-[var(--x)] 是合法的，但 text-var(--x) 是错的——后者会被当作文本类名，不解析
• :root 定义必须在 @layer base 或最外层，否则可能被覆盖；媒体查询里的定义优先级更高
• 这种写法生成的类不带色阶（bg-brand-500 不存在），只响应运行时变量变更，别混用变体类

Arbitrary Values 不支持 var()，别试

text-[var(--primary)] 看起来像能用，实际会被 Tailwind 当作字面字符串处理，最终生成 text-[var(--primary)] { --tw-text-opacity: 1; color: var(--primary); } —— 但这个类名根本不会被 JIT 引擎识别，CSS 文件里压根不出现。

Arbitrary Values 只接受静态值：数字、HEX、函数式语法（如 bg-[url('/img.png')]），所有含 var() 的写法都会被静默丢弃。

• 想动态控制某一个属性？用 @layer utilities 手写规则，别指望任意值兜底
• 大量重复写 bg-[#f1f2f3] 类，不如抽成配置里的静态色，体积和维护性都更优
• v3.3+ 支持 text-[color:var(--x)] 这种插值语法，但仅限于 @apply 内部，且依赖 :root 已定义

真正麻烦的从来不是怎么写，而是搞不清「这变量要不要运行时变」——静态就塞 HEX 到 config，动态就扔进 CSS 层，中间路线只会让构建失败、变体缺失、调试抓瞎。