运行时换肤必须用css变量+data-theme+任意值语法，因tailwind是构建时工具；theme.extend.colors不支持var()，需在safelist中放行方括号类并确保变量在@layer base中声明。
不能靠改 tailwind.config.js 实现运行时换肤，Tailwind 是构建时工具，所有 class 都在打包阶段固化；真正可行的路径只有一条：用 CSS 变量承接主题值，用 data-theme 控制作用域，用任意值语法（如 bg-[var(--color-bg)]）在 HTML/JSX 中显式引用，并确保变量被正确声明和放行。
为什么 theme.extend.colors 里不能写 var(--primary)
Tailwind 在构建时静态解析配置，此时浏览器尚未加载 CSS、JS 更未执行，var(--primary) 根本没有定义，会直接被忽略或报错。你改了配置，bg-primary 类依然不生成，DevTools 里搜不到对应规则——这不是插件没装好，是根本走不通。
常见错误现象：tailwind.config.js 保存后开发服务器没报错，但页面上 bg-primary 完全没颜色；或者你写了 text-[var(--primary)] 却标红、不生效。
-
theme.extend.colors只接受确定值：十六进制、RGB、HSL 或已知命名色（如blue-500） - 想让
bg-primary指向变量？不行。必须放弃语义化 class 名，改用bg-[var(--color-bg)]这类任意值写法 - 变量名必须以
--开头，且只能含字母、数字、连字符、下划线，var( --color-bg )或var(--color bg)都会编译失败
如何让 bg-[var(--color-bg)] 真正生效且不被 PurgeCSS 删除
Tailwind 默认跳过无法静态分析的方括号表达式。它不会主动扫描你 JS 里拼接的字符串，也不会猜你在 document.documentElement.style.setProperty() 里设了什么。必须明确告诉它：“这些字符串我要用”。
- 在
tailwind.config.js的safelist中放行：推荐正则/^bg-\[.*\]$/和/^text-\[.*\]$/，覆盖所有带方括号的背景与文字类 - 更精确的做法是列出具体使用项：
['bg-[var(--color-bg)]', 'text-[color:var(--color-text)]'] - 确保
content配置能扫描到这些字符串，例如：content: ['./src/**/*.{js,jsx,ts,tsx,html}'] - VS Code 插件标红 ≠ 编译失败，只要
safelist包含该字符串，构建就能生成对应 CSS 规则
为什么 text-[var(--color-text)] 有时不显示颜色
不是语法问题，而是变量没挂对地方，或被其他 class 覆盖。CSS 变量必须在继承链起点声明，且优先级要压得住默认样式。
- 变量必须声明在
@layer base块内，否则会被 Tailwind 默认样式覆盖；写在组件 scoped style 或普通style标签里无效 -
data-theme必须设在标签上，设在或某个 div 上会导致子元素漏继承 - 混用
text-blue-500和text-[color:var(--color-text)]时，前者会赢——因为它同时设置了color和font-weight，后者只设color；避免共存，或用text-[color:var(--color-text)] font-normal补全 - 首次渲染前建议内联默认变量：
<style>:root { --color-bg: #fff; --color-text: #1f2937; }</style>，防止闪动
切换主题时 JS 该做什么、不该做什么
JS 的职责非常轻：只负责设置根节点属性或变量，其余全部交给 CSS。别试图重写配置、别动态加载 CSS 文件、别 patch 第三方库的 class 生成逻辑。
- 切换主题只需一行：
document.documentElement.setAttribute('data-theme', 'dark')，或批量设变量：Object.entries(theme).forEach(([k, v]) => document.documentElement.style.setProperty(k, v)) - 如果用了
bg-primary/70这类带透明度的写法，必须同步设置--primary-alpha，因为 Tailwind 编译出的透明度规则依赖rgb(var(--primary) / var(--primary-alpha, 1)) - 不要混用
dark:和data-theme：dark:只响应prefers-color-scheme或class="dark"，跟自定义主题无关；混用会导致 DevTools 里颜色忽明忽暗、优先级混乱 - 最容易被忽略的是变量命名一致性：项目里同时存在
--primary、--color-primary、--theme-primary，会导致部分组件换色、部分不动；统一收口，集中写在@layer base里
整套机制的脆弱点不在 JS 切换逻辑，而在于变量声明位置、safelist 覆盖范围、以及首次渲染前的兜底初始化——这三个地方错一个，就会出现闪动、失色、或部分组件不响应。写十个切换函数不如把这三件事做扎实。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
