tailwind v4+ 推荐用 @theme 规则声明 css 变量（如 @theme { --color-primary: oklch(0.55 0.27 262); }），使其参与色阶推导并支持 data-theme 切换；v3 或需精细控制时可用 @layer utilities 显式绑定，字体等非颜色变量可安全映射 var(--x)。
tailwind.config.js 里直接写 var(--x) 会崩变体类
不能把 var(--primary) 当作颜色值塞进 theme.extend.colors.primary。Tailwind 构建时根本不会执行 CSS，parseColor() 拿到的是字符串，不是 RGB 值，后续所有依赖亮度计算的逻辑（比如 bg-primary-600、hover:bg-primary）都会出错，常见报错是 Cannot read property 'r' of undefined。
现象很典型：你写 bg-primary 能生效，但加个 -500 就没类生成；或者 hover 时背景变透明、文字变白到看不见——其实是渲染出了 color: rgb(NaN)。
- 这是设计限制，不是 bug：配置文件是纯 JS 上下文，不接入浏览器 CSS 运行时
- 如果你只是固定用一个色值（比如品牌蓝），直接写死
primary: '#1677FF'，最稳 - 如果变量真要 runtime 切换（深色模式、用户主题），别在 config 里“映射”，换路走
用 @theme 规则声明变量（Tailwind v4+ 推荐）
v4 原生支持 @theme at-rule，是目前最干净的方案。它让 CSS 变量直接成为 Tailwind 主题的一部分，无需插件、不绕开变体系统，还能配合 data-theme 切换。
在你的主 CSS 文件（如 src/index.css）里写：
@import "tailwindcss";
@theme {
--color-primary: oklch(0.55 0.27 262);
}
[data-theme="purple"] {
--color-primary: oklch(0.55 0.27 304);
}
然后 HTML 里切主题只要一行 JS：document.documentElement.dataset.theme = 'purple'。所有引用 --color-primary 的工具类（text-primary、bg-primary 等）自动响应，不用重渲染组件。
-
@theme声明的变量会被 Tailwind 解析并参与色阶推导（v4+ 支持 oklch/rgb/hsl 等格式） - 不依赖
tailwind.config.js，避免配置污染和拼写错误风险 - 变量作用域清晰：CSS 层级控制覆盖，
:root默认值 +[data-theme]覆盖，比@media (prefers-color-scheme)更可控
手动绑定变量到 utility 类（兼容旧版或特殊场景）
如果你还在用 v3 或需要精细控制某个变量的用途（比如只给背景用、不参与文本色变体），就放弃 colors 扩展，改用 @layer utilities 显式绑定。
在 CSS 文件里写：
@layer utilities {
.bg-brand {
background-color: var(--color-brand);
}
.text-brand {
color: var(--color-brand);
}
}
再确保全局 CSS 已定义该变量，例如：
:root {
--color-brand: #3b82f6;
}
.dark {
--color-brand: #60a5fa;
}
- 这种写法完全绕过 Tailwind 颜色系统，
bg-brand就是原样输出background-color: var(--color-brand) - 适合运行时动态改值：
document.documentElement.style.setProperty('--color-brand', '#ef4444') - 注意：不要和
theme.extend.colors.brand: 'var(--color-brand)'混用，否则变体冲突、构建失败
字体族等非颜色变量可以安全映射 var(--x)
字体、间距、阴影这类属性不依赖亮度解析，var(--font-sans) 在 theme.fontFamily.sans 里是安全的。
正确写法是数组形式：
fontFamily: {
sans: ["var(--font-sans)", "system-ui", "sans-serif"],
}
关键点：
- 第一项必须是字符串
"var(--font-sans)"（JS 里带引号，编译后变成无引号的 CSS 函数） - 后面跟传统回退字体链，浏览器会逐个尝试
- 变量未定义时自动降级，不会崩溃
- 字体名含空格（如
'Inter Variable'）必须用单/双引号包裹，否则 CSS 解析失败
真正容易被忽略的是作用域：变量得在 :root 或目标元素上定义好，且优先级足够高；否则 font-sans 类可能生效，但变量值为空，最终 fallback 到浏览器默认字体。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
