唯一稳定方案是data-theme+CSS变量+@layer base；变量必须定义在@layer base中以防被覆盖，safelist需放行var()类，且data-theme须设在<html>上确保继承。
直接用 data-theme 控制 CSS 变量注入，是当前 Tailwind 多主题切换唯一稳定、可维护的运行时方案。其他方式（比如改 tailwind.config.js、混用 dark:、依赖第三方插件）要么编译期固化、要么优先级混乱、要么破坏调试链路。
为什么必须把变量定义在 @layer base 里
Tailwind 的默认样式（如 bg-white、text-gray-900）生成在 @layer base 层级。如果你把 [data-theme="dark"] 的变量声明写在 @layer components 或普通 CSS 规则里，它会被默认样式覆盖——浏览器计算时，base 层的固定色值优先级高于后续层的变量声明。
正确做法是：
- 所有
:root和[data-theme="xxx"]块都包裹在@layer base { ... }中 - 确保变量名统一，例如
--color-bg、--color-text，不带主题前缀 - 避免在
@layer utilities里重复定义变量，那属于 class 映射逻辑，不是变量注入点
bg-[var(--color-bg)] 不生效的三个硬性前提
这个写法不是“写了就有效”，它依赖三件事同时成立：
立即学习“前端免费学习笔记（深入）”；
-
tailwind.config.js的safelist必须显式包含该字符串，例如：safelist: ['bg-[var(--color-bg)]', 'text-[var(--color-text)]'] - CSS 变量必须已在
:root或对应[data-theme="xxx"]块中声明，且拼写完全一致（--color-bg≠--bg-color） - HTML 中
data-theme必须设在<html>标签上，否则子元素无法继承变量作用域
VS Code 插件标红没关系，只要构建能出 CSS 规则，就是配置到位了。
切换 data-theme 时页面闪动的根本原因
不是 JS 慢，而是 CSS 加载时机错位：JS 执行 document.documentElement.setAttribute('data-theme', 'blue') 时，如果主题 CSS 文件还没解析完，浏览器会先按旧变量渲染一帧，再重绘。
缓解方法只有两个：
- 在
<head>内联一组最小化默认变量，例如：<style>:root { --color-bg: #fff; --color-text: #1f2937; }</style> - 首次加载时，用
document.documentElement.style.setProperty()同步初始化变量，绕过 CSS 文件加载延迟
别指望加 transition 或 opacity 动画掩盖问题——那是治标，变量未就绪就什么都白搭。
最易被忽略的是变量命名一致性与初始化顺序：一个项目里 --primary、--color-primary、--theme-primary 并存，会导致部分组件用 A 变量、部分用 B 变量，切换时颜色分裂。统一收口到一套命名，并在 @layer base 里集中管理，比写十个切换函数更重要。
