Tailwind CSS v3 不支持在 theme.extend.colors 中使用 var(--primary)，因其颜色系统需静态解析 RGB 值生成变体，而 CSS 变量无法被解析为数值，导致 bg-primary-500 等类缺失、hover:bg-primary 失效、dark:bg-primary 无效；正确做法是放弃扩展 colors，改用 @layer utilities 结合方括号任意值语法定义工具类，并配合 safelist、JS 动态设置变量及初始化默认值。
在 Tailwind CSS v3 中，theme.colors 无法直接写 var(--primary)，也不支持运行时动态替换——所有颜色类都在构建时静态生成。所谓“动态主题”，必须绕过 colors 配置，改用 CSS 变量 + 任意值语法 + 显式 safelist，再配合 JS 控制变量值。
为什么不能在 theme.extend.colors 里写 var(--primary)
Tailwind v3 的颜色系统依赖静态 RGB 解析：它要为每个颜色生成 -50 到 -900、/20、hover:bg-primary-600 等变体。传入 'primary': 'var(--primary)' 后，解析器拿到的是字符串字面量，不是数字，结果是：
-
bg-primary能生成（原样塞进 CSS），但bg-primary-500根本不会出现 -
hover:bg-primary渲染出color: rgb(NaN)或静默失效 -
dark:bg-primary完全无效——v3 不感知 CSS 变量作用域切换
正确做法：用 @layer utilities 绑定变量
放弃扩展 colors，转而在全局 CSS 文件中显式定义工具类，把变量“硬接”到具体属性上：
@layer utilities {
.text-primary { @apply text-[color:var(--primary)]; }
.bg-primary { @apply bg-[var(--primary)]; }
.border-primary { @apply border-[var(--primary)]; }
}
注意三点：
立即学习“前端免费学习笔记（深入）”；
- 方括号内不能有空格：
var(--primary)✅，var( --primary )❌ - 必须加
safelist放行正则：/^text-\[.*\]$/、/^bg-\[.*\]$/ - 这些类名（如
text-primary）必须在模板中字面量出现，JIT 才会生成
JS 动态设置变量时必须同步 alpha
v3 不支持 rgb(var(--primary) / <alpha>) 的自动透明度推导。如果你写了 bg-primary/70，Tailwind 实际需要 rgb(var(--primary) / var(--primary-alpha, 1)) 结构，但默认不生成 --primary-alpha 变量。
安全做法只有两个：
- JS 修改时同时设两个变量：
document.documentElement.style.setProperty('--primary', '239 68 68');和document.documentElement.style.setProperty('--primary-alpha', '0.7'); - 更推荐：不用
/70后缀，改用bg-primary opacity-70组合，完全避开 alpha 解析问题
最容易被忽略的初始化时机和作用域
JS 设置 data-theme="blue" 或 style.setProperty 之后，如果 CSS 还没加载完，浏览器会先按未定义变量渲染一帧（显示为 inherit 或 fallback 色）。这不是 bug，是执行顺序问题。
解决方法很简单：
- 在
<head>内联一组默认变量：<style>:root { --primary: 96 165 250; } - 或者，在 JS 入口最顶部批量初始化：
document.documentElement.style.setProperty('--primary', '96 165 250'); - 别混用
dark:前缀和data-theme——它们互不感知，强行共存会导致部分组件换色、部分不动
