不能靠 dark: 前缀实现多套暗黑模式，必须用 CSS 变量 + @layer base + data-theme 挂载到 <html>，并在 tailwind.config.js 中桥接 var(--xxx) 到 theme.extend.colors。
不能靠 dark: 前缀实现多套暗黑模式——它只认系统偏好或 class="dark"，不支持 data-theme="dark" 或其他主题名。 真正能切换多套主题（如 light/dark/sepia）的路径只有一条：用 CSS 变量 + @layer base + data-theme 挂载到 <html>，再在 tailwind.config.js 中桥接变量名。
为什么 dark:bg-gray-900 无法用于多主题
dark: 是 Tailwind 对 prefers-color-scheme: dark 或硬编码 class="dark" 的静态映射。它不解析任何自定义属性，也不响应 data-theme="dark"、data-theme="blue" 这类值。哪怕你写了 data-theme="dark" 在 <html> 上，dark:bg-gray-900 依然不会生效。
- 混用
dark:和data-theme会导致 DevTools 里样式忽明忽暗——因为两套机制在竞争同一元素 - 第三方 UI 库（如 Headless UI）默认只生成
dark:类，不会识别data-theme，必须手动覆盖或绕过 - 想支持“深色”只是其中一种可选主题（而非唯一暗色方案），就必须放弃
dark:作为控制开关
如何声明并挂载多主题 CSS 变量
所有变量必须写在 @layer base 块中，且作用域为 :root 或 [data-theme="xxx"]，确保能被子元素继承。变量名要统一（比如全用 --color-bg，别混用 --bg、--theme-bg）。
-
<html data-theme="dark">必须设在根标签上；设在<body>或组件内，子元素拿不到变量值 - 首次渲染前建议内联默认值，避免闪动：
<style>:root { --color-bg: #fff; --color-text: #1f2937; }</style> - 多主题示例（放在
src/index.css或全局样式文件中）：@layer base {<br> :root {<br> --color-bg: #ffffff;<br> --color-text: #1f2937;<br> }<br> [data-theme="dark"] {<br> --color-bg: #111827;<br> --color-text: #f9fafb;<br> }<br> [data-theme="sepia"] {<br> --color-bg: #f4f0e5;<br> --color-text: #4a3f35;<br> }<br>}
怎样在 tailwind.config.js 中桥接变量
不是把变量名当键写进去，而是把 var(--xxx) 当作字符串值，塞进 theme.extend.colors 对应位置。Tailwind 不会运行时求值，只负责把这串文本编译进生成的 class 规则里。
立即学习“前端免费学习笔记（深入）”；
- 正确写法：
theme: {<br> extend: {<br> colors: {<br> bg: 'var(--color-bg)',<br> text: 'var(--color-text)',<br> primary: 'var(--color-primary)'<br> }<br> }<br>} - 必须加
safelist，否则bg-[var(--color-bg)]会被 PurgeCSS 删掉：safelist: [<br> /^bg-\[.*\]$/, <br> /^text-\[.*\]$/<br>]
- 变量名中不能有空格：
var(--color-bg)合法，var( --color-bg )会编译失败 - 透明度需同步处理：
bg-[var(--color-bg)]/70要求变量本身是rgb(...)格式，不能是十六进制
JS 切换主题时最容易忽略的三个点
执行时机、作用域、持久化——三者缺一不可，否则用户刷新就回退，或首屏闪白。
- 脚本必须内联在
<head>，且不能包裹在DOMContentLoaded或useEffect里（太晚了） - 必须操作
document.documentElement，不是document.body，否则 SSR 下 hydration error - 必须用
localStorage持久化：localStorage.setItem('theme', 'dark')，否则用户点一次开关，刷新就失效 - 典型初始化代码（可直接贴入
<head>）：(() => {<br> try {<br> const saved = localStorage.getItem('theme')<br> const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches<br> const shouldDark = saved === 'dark' || (saved !== 'light' && prefersDark)<br> document.documentElement.setAttribute('data-theme', shouldDark ? 'dark' : 'light')<br> } catch {}<br>)()
最常出问题的地方不是配置写错，而是变量声明没进 @layer base、data-theme 没设在 <html>、或者 JS 初始化脚本加载晚于 CSS —— 这三处任一遗漏，都会导致变量取不到、样式不切换、或首屏先亮后暗。
