多主题暗黑模式切换不能依赖 dark: 前缀，因其仅响应系统偏好或 class="dark"，不识别 data-theme；必须用 CSS 变量 + @layer base + data-theme 挂载到 <html>，并在 tailwind.config.js 中桥接变量。
多主题暗黑模式切换不能靠 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" 的静态映射，不解析任何自定义属性。哪怕你写了 <html data-theme="dark">，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 {
:root {
--color-bg: #ffffff;
--color-text: #1f2937;
}
[data-theme="dark"] {
--color-bg: #111827;
--color-text: #f9fafb;
}
[data-theme="sepia"] {
--color-bg: #f4f0e5;
--color-text: #4a3f35;
}
}
如何在 tailwind.config.js 中桥接主题变量
关键不是重写颜色数组，而是把 --color-bg 这类变量名“透传”进 class 生成逻辑：
立即学习“前端免费学习笔记（深入）”；
- 在
theme.extend.colors里写bg: 'var(--color-bg)'，或更安全的bg: withOpacityValue('--color-bg') - 必须配置
safelist，否则bg-[var(--color-bg)]会被 PurgeCSS 删除：safelist: [/^bg-\[.*\]$/, /^text-\[.*\]$/] -
var(--color-bg)中括号内不能有空格，且必须是英文半角字符；var( --color-bg )会编译失败
最容易被忽略的初始化时机问题
JS 执行 document.documentElement.setAttribute('data-theme', 'dark') 时，如果 CSS 文件还没解析完，浏览器会先按旧变量渲染一帧。内联默认变量 + 统一命名（别混用 --primary 和 --color-primary）比写十个切换函数更重要。
变量作用域错位是 text-[var(--color-primary)] 不生效的最常见原因：所有主题变量必须写在 @layer base 块里，否则会被 Tailwind 默认样式覆盖；data-theme 必须设在 <html> 上，保证继承链完整。
