直接用CSS变量+tailwind.config.js的theme.extend+darkMode:'class'即可支持任意主题切换，无需插件；插件会破坏变量追踪、与@apply冲突且Tailwind 4升级后失效。
直接用 CSS 变量 + tailwind.config.js 的 theme.extend + darkMode: 'class' 就能支持任意数量的主题切换，不需要插件。插件反而会破坏变量可追踪性、与 @apply 冲突、且 Tailwind 4 升级后大概率失效。
为什么不能依赖第三方主题插件
像 tailwindcss-theming 这类插件会劫持 theme.colors 解析流程，导致：
-
bg-primary在不同主题下可能指向不同层级的var(--xxx)，DevTools 里点不到最终值 - 和
@apply、group-hover:组合时容易丢失上下文，生成冗余规则 - 插件依赖 Tailwind 内部 AST 解析逻辑，官方不承诺这部分 API 稳定，升级到 v4 后基本不可用
如何在 tailwind.config.js 中桥接 CSS 变量
关键不是重写颜色数组，而是把变量名“透传”进 Tailwind 的 class 生成系统：
- 在
theme.extend.colors中用withOpacityValue或直接写var(--color-primary)（需确保变量已定义） - 必须配置
safelist，否则bg-[var(--color-bg)]会被构建器忽略 - 推荐写法：
safelist: [/^bg-\[.*\]$/, /^text-\[.*\]$/]，或精确列出：['bg-[var(--color-bg)]', 'text-[var(--color-text)]'] -
var(--color-bg)中括号内不能有空格，且必须是英文半角字符，否则编译失败
主题变量必须定义在 @layer base 且挂载到 <html>
变量作用域错位是 text-[var(--color-primary)] 不生效的最常见原因：
立即学习“前端免费学习笔记（深入）”；
- 所有主题变量必须写在
@layer base块里，否则会被 Tailwind 默认样式覆盖 -
data-theme必须设在<html>标签上，保证继承链完整；设在<body>或组件上会漏继承 - 不要混用
dark:和data-theme——dark:只响应prefers-color-scheme或class="dark"，跟自定义主题无关 - 首次渲染前建议内联一组默认变量（比如在
<head>里加<style>:root { --color-bg: #fff; }</style>），避免闪动
最易被忽略的是变量初始化时机：JS 执行 document.documentElement.setAttribute('data-theme', 'blue') 时，如果 CSS 还没加载完，浏览器会按未定义变量回退为 inherit 渲染一帧。务必确保变量定义早于 DOM 渲染。
