@theme指令必须位于css文件顶层且不可嵌套，否则被忽略；需配合theme()函数桥接工具类，变量结构须匹配主题路径（如colors.primary），否则bg-primary等类无法解析。
@theme 指令必须放在 CSS 文件顶层，且不能嵌套
Tailwind CSS v4 废弃了 tailwind.config.js，改用纯 CSS 方式管理主题变量，核心是 @theme 指令。它只能出现在 CSS 文件最开头（所有规则之前），且不能包在 @layer、@media 或其他块级规则里，否则会被忽略。
- ✅ 正确位置：
@theme { --color-primary: #3b82f6; }直接写在input.css第一行 - ❌ 错误写法：
@layer base { @theme { ... } }——@theme不支持嵌套 - ❌ 错误写法：
.foo { @theme { ... } }—— 不能在选择器内部声明 - ⚠️ 注意：同一文件中多个
@theme块会合并，但顺序不保证，建议只写一个
如何让自定义变量被 Tailwind 工具类识别
光写 @theme 不够，还得在 @tailwind utilities（或 @import "tailwindcss"）之前，用 theme() 函数桥接到工具类系统。否则 bg-primary 这类 class 无法解析成 background-color: var(--color-primary)。
- 必须显式调用
theme("colors.primary")，例如：.bg-primary { background-color: theme("colors.primary"); } - 不能直接写
background-color: var(--color-primary)—— 这样不会参与 Tailwind 的响应式、暗色模式等逻辑 - 颜色值支持 HEX、RGB、CSS 变量，但
theme()只读取静态配置，不支持动态键（如theme("colors." + $name)） - 如果用了
darkMode: 'class'，需额外定义[data-theme="dark"] { @theme { --color-primary: #2563eb; } }
为什么 @layer base 里定义变量经常失效
很多人把 --color-primary 写进 @layer base，结果 theme("colors.primary") 解析为空。这不是 bug，而是作用域问题：@theme 是独立指令，和 @layer 无关，变量必须由 @theme 显式声明才能被 theme() 函数读取。
- ❌ 错误：
@layer base { :root { --color-primary: #3b82f6; } }→theme("colors.primary")返回 undefined - ✅ 正确：
@theme { colors: { primary: "#3b82f6" } }→theme("colors.primary")返回#3b82f6 - ⚠️ 注意：
@theme中的结构要匹配 Tailwind 主题路径，比如spacing.4对应@theme { spacing: { 4: "1rem" } } - 常见遗漏：忘记给自定义颜色加透明度变体（如
primary: { 50: "...", 100: "..." }），导致bg-primary-50类不存在
使用 @theme 后如何调试变量是否生效
最直接的办法是在浏览器 DevTools 的 Styles 面板里检查元素 computed 样式，看 background-color 是否解析为实际值；更可靠的是在 CSS 文件里临时加一条测试规则：
.debug-theme {
content: theme("colors.primary");
/* 在 DevTools 里 hover 这行，看是否显示 #3b82f6 */
}
- 如果显示
theme("colors.primary")字面量，说明@theme未被识别或路径错误 - 如果显示空值，检查是否拼错键名（如写成
primay）、是否漏掉外层对象包装（@theme { colors: { ... } }） - Vite 环境下，修改
@theme后需手动刷新页面，HMR 不会触发 CSS 主题重编译
Tailwind v4 的主题系统绕开了 JS 配置，但对 CSS 书写顺序和结构更敏感——@theme 的位置、嵌套限制、与 theme() 的配对关系，三者缺一不可。稍有偏差，变量就“存在却不可见”。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
