不能在 tailwind.config.js 里直接写 var(--color-brand)，因为 Tailwind 构建时需静态解析颜色值以生成色阶、透明度等变体，而 var() 是运行时变量，无法提取 r/g/b 分量，导致色阶失效和 NaN 错误；应静态配置 HEX 值如 brand: '#1677FF'，或改用 @layer utilities + var() 实现运行时主题切换。
不能在 tailwind.config.js 里直接写 var(--color-brand) —— 这不是配置错误，是 Tailwind 构建机制决定的硬性限制。
为什么 tailwind.config.js 里用 var() 会崩？
Tailwind 在构建时必须静态解析所有颜色值，才能生成 bg-brand-500、bg-brand/20、hover:bg-brand-600 这类变体。而 var(--color-brand) 是运行时才求值的字符串，parseColor() 拿到的是字面量 "var(--color-brand)"，根本抽不出 r/g/b 分量。结果就是：类名能生成，但所有色阶、透明度、暗化逻辑全失效，控制台报 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 正常工作。
真需要运行时切换主题？改用 @layer utilities + var()
当你需要支持用户点击切换主题、响应 prefers-color-scheme、或 JS 动态调用 document.documentElement.style.setProperty('--color-primary', ...) 时，必须绕过配置文件，在 CSS 层级绑定变量。
- 确保全局已定义该变量，例如在
@tailwind base前写：
:root {
--color-brand: #1677FF;
}
@media (prefers-color-scheme: dark) {
:root {
--color-brand: #60a5fa;
}
}
- 在主 CSS 文件（如
src/index.css）里用@layer utilities绑定：
@layer utilities {
.text-brand { @apply text-[var(--color-brand)]; }
.bg-brand { @apply bg-[var(--color-brand)]; }
.border-brand { @apply border-[var(--color-brand)]; }
}
注意：@apply text-[var(--x)] 这种写法只适用于工具类，不参与 Tailwind 的色阶推导，也不支持 bg-brand-500 这类变体 —— 它就是纯运行时取值，仅适合明确需要动态性的场景。
最容易被忽略的点
@layer utilities 中的 text-[var(--x)] 类不会自动获得响应式前缀（如 md:text-brand）或 dark: 变体，因为 Tailwind 不解析括号内表达式；若需深色模式下不同变量，得手动写两套规则，例如：
@layer utilities {
.text-brand { @apply text-[var(--color-brand)]; }
.dark .text-brand { @apply text-[var(--color-brand-dark)]; }
}
另外，所有使用这些类的 HTML 文件路径，必须包含在 tailwind.config.js 的 content 数组中，否则类根本不会生成 —— 配置再对，漏了 ./src/**/*.{vue,jsx,tsx} 就等于白干。
