Tailwind 配置中 theme.extend.colors 不支持 var(--primary)，必须用确定色值；动态变量需在 HTML/JSX 中显式使用如 bg-[var(--bg-surface)]，并配置 safelist 和 content 扫描路径，同时确保 CSS 变量在 :root 或 data-theme 下提前声明。
tailwind.config.js里不能直接写var(--primary)
Tailwind 在构建时静态解析配置，tailwind.config.js里的 theme.extend.colors 必须是确定的色值（如 #3b82f6 或 rgb(59, 130, 246)），写 var(--primary) 会被忽略或报错——它不是运行时变量，而是编译期常量。
常见错误现象：配置保存后开发服务器没报错，但 bg-primary 类根本没生成，DevTools 里查不到对应 CSS 规则。
- 真正能用
var()的地方只在 class 值中，比如bg-[var(--bg-surface)] - 必须确保该字符串出现在源码里（HTML/JSX 中显式写出），否则 Tailwind 扫描不到，不会生成规则
- 变量名必须符合 CSS 自定义属性规范：以
--开头，只能含字母、数字、连字符和下划线，不能有空格或中文
text-[var(--text-color)]不生效的三个真实原因
不是语法写错了，而是运行时环境没兜住：
-
--text-color没在:root或[data-theme]下声明，var()回退为inherit，最终颜色不可见 - 混用了
text-blue-500和text-[color:var(--text-color)]—— 前者设置了color+font-weight，后者只设color，被覆盖 - CSS 优先级问题：
@layer base里定义的变量如果写在 Tailwind 默认样式之后，可能被覆盖；必须把变量声明放在@layer base块内，且确保加载顺序靠前
如何让 bg-[var(--bg-surface)] 安全通过构建
Tailwind 默认会跳过无法静态分析的方括号表达式，必须主动放行：
立即学习“前端免费学习笔记（深入）”；
- 在
tailwind.config.js中配置safelist，推荐正则写法：/^bg-\[.*\]$/和/^text-\[.*\]$/ - 或者精确列出：
['bg-[var(--bg-surface)]', 'text-[color:var(--text-primary)]'] - 方括号内不能有空格，
bg-[var( --bg-surface )]会编译失败；也不能用中文引号或全角符号 - 确保
content配置正确扫描到这些字符串，例如：content: ['./src/**/*.{js,jsx,ts,tsx,html}']
切换皮肤时最容易漏掉的初始化时机
JS 执行 document.documentElement.setAttribute('data-theme', 'dark') 后，页面可能闪一下白底——因为 CSS 文件还没加载完，浏览器先按无变量状态渲染了一帧。
解决办法不是加 loading，而是提前兜底：
- 在
<head>里内联一组默认变量，比如：<style>:root { --bg-surface: #fff; --text-primary: #1e293b; }</style> - 或者用
document.documentElement.style.setProperty()在 JS 加载早期就设置好初始值 - 不要依赖
dark:和data-theme混用，dark:只响应系统偏好或class="dark"，跟自定义主题无关
变量作用域和初始化顺序，比怎么写 class 更关键。没声明、没加载、没继承，再对的语法也白搭。
