Tailwind 无法解析 CSS 变量如 var(--x) 生成色阶，theme.extend.colors 中填 'var(--primary)' 会导致 bg-primary-500 等变体缺失或报错；正确做法是静态写死 HEX 值（推荐）或运行时用 @layer base 定义 :root 变量 + 手动 utility class。
tailwind.config.js 里写 var(--x) 会失效
直接在 theme.extend.colors 或 theme.fontFamily 里填 'var(--primary)' 看似合理，但 Tailwind 构建时根本不会解析这个字符串——它只当普通文本输出。结果是：bg-primary 类生成了，但 bg-primary-500、hover:bg-primary 全部缺失或报错，因为 Tailwind 的颜色系统需要真实 RGB 值来推导色阶和变体。
常见错误现象：
- 开发服务器启动时报
Cannot read property 'r' of undefined - 页面上
bg-primary有效，但加了-hover后背景消失或变成透明 - 控制台无报错，但样式渲染为
color: rgb(NaN)
真正能同步的两种方式：静态值 or 运行时绑定
别试图让 Tailwind “读取” CSS 变量，它做不到。你得选清楚：是要编译期确定样式（用静态 HEX），还是运行时切换主题（用 CSS 变量 + 手动 class）。
静态复用（推荐多数场景）：
立即学习“前端免费学习笔记（深入）”；
- 在
tailwind.config.js中直接写死值，比如primary: '#3b82f6'，确保所有变体正常生成 - 把设计系统主色统一收口到一个 JS 常量文件，再
require进 config，保持源头一致 - 字体族可安全用
["var(--font-sans)", "system-ui"]，Tailwind 会原样输出，浏览器负责解析
运行时切换（深色模式/主题热更新）：
使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。
- 放弃在 config 里映射变量，改用
@layer base在全局 CSS 中定义:root和[data-theme="dark"] - 手动写 utility class：
.bg-brand { background-color: var(--color-brand); }，再用@apply bg-brand - 必须把
data-theme设在<html>上，否则变量无法继承
safelist 和 @layer utilities 是关键开关
如果你坚持用 bg-[var(--color-bg)] 这种写法，Tailwind 默认不会生成对应 CSS —— 它只扫描模板中真实出现的类名，而 var() 是运行时表达式，不属于原子类。
必须显式配置：
- 在
tailwind.config.js的safelist中加入完整字符串，例如'bg-[var(--color-bg)]' - 所有变量声明必须包裹在
@layer base { }里，否则会被 Tailwind 默认样式覆盖 - VS Code 插件标红没关系，只要构建后 CSS 文件里真有那条规则，就说明配置到位
插件不是必需，但能降低出错概率
tailwind-css-variables 这类插件的作用，是帮你自动补 fallback（如 var(--color, #3b82f6)）并校验变量是否存在。但它不解决根本限制：Tailwind 依然无法从 var(--x) 推导色阶。
是否值得引入？
- 项目只需固定主题 → 不装，手写
:root+@layer utilities更轻量 - 需批量管理几十个变量且要求 fallback → 插件能省掉重复写
var(--x, #xxx)的麻烦 - 装了插件后，仍需在
plugins: []中显式调用，否则配置里的var()不会被增强
最容易被忽略的是变量命名一致性：同一个颜色，在 :root 里叫 --primary，在组件 style 里又写成 --theme-primary，切换时必然分裂。统一收口，比写十个切换函数重要得多。
