不能在 tailwind.config.js 中直接使用 var(--x) 配色，因其需静态解析 RGB 值以生成色阶、透明度等变体，而 CSS 变量为运行时求值；应将 HEX 值写入 colors 扩展中（如 brand: '#1677FF'），或改用 @layer utilities + var() 实现运行时主题切换。
不能在 tailwind.config.js 里直接用 var(--x) 配颜色，这不是配置写错，是 Tailwind 构建机制决定的——它需要静态解析出 r/g/b 值来生成 bg-brand-500、bg-brand/20、hover:bg-brand-600 这类变体，而 CSS 变量是运行时才求值的字符串，parseColor() 拿到的是字面量 "var(--brand)"，根本抽不出颜色分量，结果就是类名能生成，但所有色阶、透明度、暗化逻辑全崩，控制台报 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 层级绑定变量。
立即学习“前端免费学习笔记（深入）”；
- 在主 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;
}
}
注意：@apply 在 @layer utilities 中是安全的，但不能用于动态值（如 text-[var(--size)]），那得靠插件 + matchUtilities。
想让自定义类支持响应式或深色模式？手动展开，别指望自动继承
用 @layer utilities 写的类不会自动获得 md: 前缀或 dark: 变体——Tailwind 不会为它注入媒体查询或选择器组合逻辑。
- 要支持响应式，得自己写媒体查询：
@layer utilities {
@media (min-width: 768px) {
.md\:text-brand { @apply text-[var(--color-brand)]; }
}
}
- 要支持深色模式，得显式组合选择器：
@layer utilities {
.dark .dark\:bg-brand { background-color: var(--color-brand); }
}
这类写法容易漏、难维护。如果需求复杂（比如要同时支持 md:dark:bg-brand），不如回到插件路线，用 addUtilities + 手动展开对象键，或改用 matchUtilities 控制生成逻辑。
最容易被忽略的是：CSS 变量必须在 :root 或对应作用域里提前声明，否则 var(--x) 返回空字符串，浏览器 fallback 到 inherit 或初始值；另外，@apply 不能嵌套在 @media 内部（某些版本会报错），稳妥做法是把 @apply 拆成原生声明。
