运行时换肤必须用CSS变量+任意值语法+JS动态设置，因Tailwind是构建时工具；bg-[var(--color-bg)]不生效主因是变量未在:root或[data-theme]下声明、未放@layer base、被高优先级类覆盖、data-theme未设在<html>上；需在safelist中放行方括号类名、确保content扫描到、JS同步设置变量、首屏内联默认值、统一变量命名。
不能靠修改 tailwind.config.js 里的 theme.extend.colors 实现运行时换肤——Tailwind 是构建时工具，所有类名都在打包阶段固化，改配置必须重启构建才生效。真正能动态换肤的，只有 CSS 变量 + HTML 中显式使用的任意值语法 + JS 运行时设置这三者配合。
为什么 bg-[var(--color-bg)] 不生效？
常见现象是 DevTools 里查不到对应 CSS 规则，或者颜色没变但 class 名字写对了。根本原因不是语法错，而是：
-
--color-bg没在:root或[data-theme="xxx"]下声明，var()回退为inherit，最终不可见 - 变量定义没放在
@layer base块里，被 Tailwind 默认样式（如bg-white）覆盖 - 混用了
bg-white和bg-[var(--color-bg)]，前者优先级更高且设了具体值，后者被静默忽略 -
data-theme没设在<html>标签上，子元素无法继承变量
如何让 text-[color:var(--text-primary)] 安全通过构建？
Tailwind 默认跳过无法静态分析的方括号表达式，必须主动放行：
- 在
tailwind.config.js的safelist中加正则：/^text-\[.*\]$/和/^bg-\[.*\]$/ - 或精确列出：
['text-[color:var(--text-primary)]', 'bg-[var(--color-bg)]'] - 确保
content配置扫描到这些字符串，例如：content: ['./src/**/*.{js,jsx,ts,tsx,html}'] - 方括号内不能有空格：
bg-[var(--color-bg)]✅，bg-[var( --color-bg )]❌
切换主题时 JS 设置变量的正确姿势
只调用 document.documentElement.setAttribute('data-theme', 'dark') 不够，因为变量值还没更新：
立即学习“前端免费学习笔记（深入）”；
- 用
document.documentElement.style.setProperty('--color-bg', '#111827')批量设置，比切 class 更直接 - 把整套皮肤变量封装成对象，用
Object.entries(theme).forEach(([k, v]) => ...)同步写入 - alpha 通道要单独设：
--primary-alpha，否则bg-primary/70这类带透明度的类会失效（它依赖rgb(var(--primary) / var(--primary-alpha, 1))） - 首次渲染前务必在
<head>内联默认变量，例如：<style>:root { --color-bg: #fff; --text-primary: #1e293b; }</style>，否则首屏闪白
最容易被忽略的是变量命名一致性：项目里同时存在 --primary、--color-primary、--theme-primary，会导致部分组件换色、部分不动。所有变量必须统一收口，全部定义在 @layer base 中，且只在 :root 或 [data-theme] 下声明。
