直接用 CSS 变量 + Tailwind 的 theme.extend 配合 darkMode: 'class' 即可支持多套皮肤，无需第三方插件；插件会劫持颜色解析、破坏调试与兼容性，而原生方案通过 :root 和 [data-theme] 定义变量、在配置中桥接 var(--xxx)，再由 setTheme 切换并持久化，简洁可控。
直接用 CSS 变量 + tailwindcss 的 theme.extend 配合 darkMode: 'class' 就能支持多套皮肤，不需要额外插件——所谓“插件实现”其实是误解，Tailwind 本身不依赖插件管理主题，插件（如 tailwindcss-theming）反而增加维护负担、破坏变量可预测性。
为什么不用第三方主题插件
第三方插件（比如 tailwindcss-theming）会劫持 theme.colors 解析逻辑，导致：
-
bg-primary在不同主题下可能指向不同层级的变量，调试时无法在 DevTools 里直接追踪到最终 CSS 变量值 - 与
@apply、group-等伪类组合使用时容易丢失上下文，生成冗余 CSS - 升级 Tailwind 4 后大概率失效，因为插件依赖内部 AST 解析细节，而官方不承诺这部分 API 稳定
用原生 CSS 变量定义多套主题色
把主题色全部收口到 :root 和带 class 的 scope 下，例如：
:root {
--color-bg: #ffffff;
--color-text: #1f2937;
--color-primary: #3b82f6;
}
[data-theme="dark"] {
--color-bg: #111827;
--color-text: #f9fafb;
--color-primary: #60a5fa;
}
[data-theme="sepia"] {
--color-bg: #f4f0e5;
--color-text: #4a3f35;
--color-primary: #c08c5a;
}
这样做的好处是：所有主题都共用同一套语义化变量名，切换只需改 data-theme 值，无需重写 class。
立即学习“前端免费学习笔记（深入）”；
在 tailwind.config.js 中桥接 CSS 变量
让 Tailwind 的 colors 直接引用这些变量，而不是硬编码值：
module.exports = {
darkMode: 'class',
theme: {
extend: {
colors: {
bg: 'var(--color-bg)',
text: 'var(--color-text)',
primary: 'var(--color-primary)',
}
}
}
}
注意几点：
- 必须用
var(--xxx)形式，不能写成rgb(var(--xxx))，否则 Tailwind 解析失败 - 如果需要透明度（如
bg-primary/20），得确保对应 CSS 变量输出的是 RGB 元组（如--color-primary: 59, 130, 246），然后在 config 里写primary: 'rgb(var(--color-primary) / <alpha-value>)' - 不要在
theme.colors里重复定义dark:子对象——那会和data-theme冲突，优先级混乱
运行时切换主题并持久化
切换本质就是操作 document.documentElement.dataset.theme：
function setTheme(theme) {
document.documentElement.dataset.theme = theme
localStorage.setItem('theme', theme)
}
// 初始化时读取
const saved = localStorage.getItem('theme') || 'light'
setTheme(saved)
关键细节：
- 别用
class切换暗色模式（如document.body.classList.toggle('dark')），那只能支持两套；data-theme才是扩展多主题的正解 - 服务端渲染（如 Next.js）需在
useEffect或useLayoutEffect里执行，避免 hydration mismatch - CSS 变量继承自
:root，所以data-theme必须设在<html>上，设在<body>会导致子元素拿不到
真正麻烦的不是配置，而是设计系统层面的约束：每套主题必须保证所有语义变量（--color-bg、--color-border、--color-disabled……）都覆盖完整，漏一个就可能让某个组件在某主题下完全不可读。这没法靠工具自动补全，得靠文档和 PR 检查卡住。
