必须用 theme.extend.colors 安全映射 CSS 变量，如 primary: 'var(--color-primary)'，避免覆盖内置颜色；变量需在 :root 或 [data-theme] 中预定义，并通过 setAttribute 切换主题，确保首屏无闪烁。
直接在 tailwind.config.js 的 theme.extend.colors 中引用 var(--color-primary) 就能实现主题色与 CSS 变量绑定，但必须确保变量已在 HTML 中定义，且配置未覆盖默认颜色结构。
tailwind.config.js 里怎么安全映射 CSS 变量到 colors
不能写成 theme.colors = { primary: 'var(--color-primary)' } ——这会清空所有内置色（blue、gray 全失效）。必须用 extend，且只注入新键名：
module.exports = {
theme: {
extend: {
colors: {
primary: 'var(--color-primary)',
secondary: 'var(--color-secondary)',
bg: 'var(--color-bg)',
text: 'var(--color-text)'
}
}
}
}
- 变量名（如
--color-primary）必须提前在:root或带 class 的 scope（如[data-theme="dark"]）中声明，否则渲染为空值 - 若需支持透明度（如
text-primary/70），得额外配置theme.extend.opacity或用withOpacity工具函数，否则/70后缀不生效 - 自定义变量名建议统一前缀（如
--theme-primary），避免和第三方库冲突
HTML 中如何声明并切换这些 CSS 变量
仅靠 JS 改 document.documentElement.style.setProperty() 不够——它只能设单个变量，无法批量切换整套主题。推荐用 data-theme + scoped :root 规则：
: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;
}
- 切换主题只需
document.documentElement.setAttribute('data-theme', 'dark') - 务必在页面加载早期（比如
<head>内联脚本）读取localStorage并设置初始data-theme，否则首屏闪白/闪黑 - 不要用
darkMode: 'media'配合这套方案——它依赖系统偏好，无法手动控制多主题
为什么 tailwindcss-theming 等插件反而容易出问题
这类插件本质是劫持 theme.colors 解析流程，在构建时生成多套 class。但实际带来三个硬伤：
立即学习“前端免费学习笔记（深入）”；
- DevTools 里查
bg-primary样式时，最终指向的 CSS 变量路径不可见，调试断点失效 - 与
@apply或group-hover:bg-primary组合时，插件可能漏解析上下文，导致 hover 状态颜色错乱 - Tailwind 4 升级后，插件依赖的内部 AST 接口大概率变更，维护成本陡增
原生 CSS 变量方案没有运行时编译负担，所有逻辑都在浏览器执行，变量名、作用域、优先级完全可控——唯一要盯紧的，是 tailwind.config.js 里别误删 extend，也别漏掉 data-theme 的初始设置时机。
