不能在tailwind.config.js的theme.extend.colors中直接使用var(--primary)，因Tailwind构建时需静态解析颜色值生成色阶和变体，而var()是运行时机制，无法提取r/g/b分量，导致bg-primary-500等变体缺失或报错Cannot read property 'r' of undefined；应优先用HEX值如brand: '#1677FF'配置以确保稳定性和完整变体支持。
不能在 tailwind.config.js 的 theme.extend.colors 里直接写 var(--primary) —— Tailwind 构建时会报错或生成无效类，这不是配置姿势问题，是底层设计限制。
为什么 var(--x) 写进 colors 会崩
Tailwind 要静态解析每个颜色值，才能生成 bg-primary-500、hover:bg-primary-600、bg-primary/20 这类变体。而 var(--primary) 是运行时才求值的字符串，parseColor() 拿到的是字面量，根本抽不出 r/g/b 分量。
-
bg-primary类能生成，但bg-primary-500完全不出现 -
hover:bg-primary渲染出color: rgb(NaN)或直接崩溃 -
dark:bg-primary无效，因为变量本身没切换逻辑 - 控制台可能报
Cannot read property 'r' of undefined
想复用固定色值？直接写 HEX，别碰 var()
如果你只是把设计系统里的 --color-brand: #1677FF 当一个新品牌色名来用（比如想写 text-brand），就别绕路——这是最稳、最兼容、零风险的做法。
- 在
tailwind.config.js中这样配：brand: '#1677FF' - 之后就能用
text-brand、bg-brand-500、hover:bg-brand-600，所有变体自动可用 - 深色模式配合
dark:bg-brand-700正常工作 - 不需要额外声明 CSS 变量，也不依赖 JS 或 :root
真需要运行时切换主题？绕过 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)]; } } - 确保变量已定义在
@layer base的:root或[data-theme]里，不能写在@layer components或顶层 - 任意值语法（如
bg-[var(--bg-surface)]）需在tailwind.config.js的safelist中显式放行，否则构建时被忽略 - 变量名必须以
--开头，拼错或未定义时浏览器回退为transparent或继承值，控制台无提示，排查困难
插件 tailwind-css-variables 什么时候值得装
原生 Tailwind 不处理 CSS 变量 fallback 或批量注入。这个插件的作用，是帮你把变量映射成带 fallback 的值（如 var(--color, #3b82f6)），并支持在 theme.extend 中更安全地引用。
- 基础场景不用装：纯手动管理
:root+var(--x)就够用 - 需要 fallback 或一次性注入几十个变量时才值得引入
- 插件注册后，仍需在
plugins: []中显式调用，否则配置里的var()不会被增强 - 它不改变变量定义位置——你依然得在 CSS 里提前声明
--primary，插件只管“怎么用”，不管“在哪定义”
真正容易被忽略的点是：CSS 变量必须在 @tailwind base 阶段就存在，否则 bg-[var(--x)] 这类任意值写法会在 PostCSS 阶段被忽略；而 @layer base 块里写变量，必须包在 :root 或 [data-theme] 选择器内，不能裸写在块顶层。
