tailwind.config.js 中不能直接使用 var(--x)，因构建时需静态解析颜色值生成变体，而 css 变量为运行时求值；应优先用 hex 值配置 theme.extend.colors，或改用 @layer utilities / @theme 规则绑定变量。
tailwind.config.js 里直接写 var(--x) 会崩，不是配置错，是设计限制
Tailwind 构建时要静态解析颜色值生成 bg-primary-500、hover:bg-primary-600、bg-primary/20 这类变体，而 var(--primary) 是运行时才求值的字符串，parseColor() 拿到的是字面量，根本抽不出 r/g/b 分量。结果就是：bg-primary 类能出来，但所有色阶、透明度、暗化逻辑全失效，控制台报 Cannot read property 'r' of undefined 或渲染出 color: rgb(NaN)。
静态复用固定色值？别绕路，直接写 HEX 到 theme.extend.colors
如果你只是把设计系统里的 --color-brand: #1677FF 当作一个新品牌色名来用（比如想写 text-brand），就别碰 var() —— 这是最稳、最兼容、零风险的做法。
-
tailwind.config.js中这样配：
module.exports = {
theme: {
extend: {
colors: {
brand: '#1677FF',
},
},
},
}
之后就能直接用 text-brand、bg-brand-500、hover:bg-brand-600，所有变体自动可用，深色模式也能配合 dark:bg-brand-700 正常工作。
真需要运行时切换主题？放弃 config，改用 @layer utilities + var()
当你要支持用户点击切换主题、响应 prefers-color-scheme、或 JS 动态调用 document.documentElement.style.setProperty('--color-primary', ...) 时，必须绕过配置文件，在 CSS 层级绑定变量。
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
- 在主 CSS 文件（如
src/index.css）里写：
@layer utilities {
.text-brand { @apply text-[var(--color-brand)]; }
.bg-brand { @apply bg-[var(--color-brand)]; }
.border-brand { @apply border-[var(--color-brand)]; }
}
- 确保全局已定义该变量，例如在
@tailwind base前写：
:root {
--color-brand: #1677FF;
}
@media (prefers-color-scheme: dark) {
:root {
--color-brand: #60a5fa;
}
}
注意：这类 utility 不会生成色阶，bg-brand-500 不存在，只能用 bg-brand；也不支持 /20 透明度语法，得靠 bg-[var(--color-brand)]/20 手动写。
Tailwind v4+ 用户优先用 @theme 规则
v4 开始原生支持 @theme at-rule，这是目前最干净的“CSS 变量即 Tailwind 类名”方案，不用手写 @layer utilities。
- 在
src/index.css里写：
@import "tailwindcss";
@theme {
--color-primary: #1677FF;
--color-secondary: #6b7280;
}
@layer utilities {
.text-primary { @apply text-[var(--color-primary)]; }
.bg-primary { @apply bg-[var(--color-primary)]; }
}
变量声明和工具类解耦更清晰，且 @theme 块本身会被 Tailwind 解析并注入到主题上下文中——但注意，它依然不参与色阶生成，只提供变量引用能力。真正容易被忽略的是：无论用哪种方式，var(--x) 的拼写、作用域、默认值 fallback 都得你自己管，Tailwind 完全不校验。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
