必须在@layer base中定义CSS变量并置于:root或[data-theme]内，否则bg-[var(--x)]等任意值写法无法响应变化，因Tailwind仅在@tailwind base阶段解析变量，后续层注入过晚导致构建时忽略。
必须在 @layer base 中定义，且变量声明要写在 :root 或 [data-theme] 选择器内部，否则 Tailwind 的 bg-[var(--color-bg)] 等任意值写法无法响应变化。
为什么不能在 @layer utilities 或 @layer components 里定义 CSS 变量
Tailwind 的层注入顺序是固定的：@tailwind base → @tailwind components → @tailwind utilities。CSS 变量需要在所有工具类解析前就存在，否则像 bg-[var(--color-bg)] 这类 arbitrary value 会在构建时被忽略（PostCSS 阶段找不到变量定义）。@layer utilities 和 @layer components 注入位置太靠后，变量“还没出生，工具类就已经编译完了”。
-
@layer base是唯一能确保变量在 Tailwind 解析工具类前就注册成功的层 - 写在普通
.css文件顶层（没包在@layer里）也不行——它可能被 Tailwind 的@tailwind base覆盖或打乱优先级 - 如果项目用了
preflight: false，更得靠@layer base同时补变量 + 重置，不能拆开
@layer base 中定义变量的正确写法
变量必须绑定到 :root 或主题选择器（如 [data-theme="dark"]），不能直接写在 @layer base 块顶层：
@tailwind base;
@tailwind components;
@tailwind utilities;
@layer base {
:root {
--color-bg: #ffffff;
--color-text: #1f2937;
--space-unit: 0.5rem;
}
[data-theme="dark"] {
--color-bg: #111827;
--color-text: #f9fafb;
}
}
- 变量名必须以
--开头，否则bg-[var(--color-bg)]会解析失败 - 不要用
@apply在这里设变量值，@apply不处理 CSS 变量声明 - 如果只用单主题，
:root就够了；多主题必须配data-theme属性切换，且data-theme要加在<html>上
怎么让 bg-[var(--color-bg)] 这类写法生效
Tailwind 默认不扫描 CSS 变量，需在 tailwind.config.js 的 safelist 中显式放行：
立即学习“前端免费学习笔记（深入）”；
module.exports = {
safelist: [
'bg-[var(--color-bg)]',
'text-[var(--color-text)]',
'p-[var(--space-unit)]',
],
}
- 每个用到的
var()组合都要单独列进safelist，不能写bg-[var(--*)]通配 - 变量值若含单位（如
--space-unit: 0.5rem），p-[var(--space-unit)]才能正确转成padding: 0.5rem - 若变量值是颜色关键词（如
--color-bg: red），bg-[var(--color-bg)]也能工作，但推荐用十六进制或 rgb() 保证跨浏览器一致性
容易被忽略的继承与作用域问题
CSS 变量默认是继承的，但某些场景下会断掉：
-
iframe内内容不继承父页面的:root变量，得在 iframe 自己的 CSS 里重新定义 - Shadow DOM 中的组件不会自动获取外部
:root变量，需在:host或::slotted里手动设置 - 如果用了 CSS-in-JS 库（如 Emotion），它生成的样式可能不在同一作用域，变量需重复注入或改用
style标签动态写入 -
[data-theme]切换后，旧变量不会自动清除，建议用 JS 清空非当前主题的属性，避免残留
