@theme必须写在@import 'tailwindcss';之后且同文件，变量名须带--color-/--font-等标准前缀，否则Oxide引擎不识别、类名不生成；顺序错或前缀错均导致静默失效。
必须把 @theme 写在 @import "tailwindcss"; 之后、同一 CSS 文件里，且变量名严格带 --color- / --font- / --breakpoint- 等前缀，否则类名（如 bg-primary、font-sans）根本不会生成——不是编译慢，是 Oxide 引擎压根不识别。
为什么 @theme 声明后类名没出现？
常见错误是顺序或前缀不对。Oxide 引擎只扫描满足两个硬性条件的 @theme 块：它必须出现在 @import "tailwindcss"; 之后，且所有变量名必须带标准前缀。
-
@import "tailwindcss";必须用单引号、末尾带分号；写成双引号、漏分号、或写成@tailwind base都会导致整个 Tailwind 处理链静默失效 -
--color-primary✅ 有效；--primary❌、--my-color❌、--colors-primary❌ —— 拼错一个连字符或前缀类型，引擎直接跳过 - 跨文件声明无效：
@theme必须和@import在同一个 CSS 文件中（如src/index.css），不能拆到theme.css单独引入
@theme 支持哪些变量前缀？
不同前缀触发不同类名生成逻辑，不能混用或自定义命名规则：
- 颜色：
--color-primary→ 生成bg-primary、text-primary、border-primary及其色阶（如bg-primary-500） - 字体：
--font-sans→ 生成font-sans；--font-serif→font-serif - 断点：
--breakpoint-xl2→ 生成xl2:w-full；值必须是合法 CSS 宽度（如1920px或120rem） - 间距/尺寸：
--spacing-6→p-6；--size-4→h-4、w-4
如何验证 @theme 是否生效？
别只看 HTML 类名有没有补全，直接查运行时或构建产物：
立即学习“前端免费学习笔记（深入）”；
- 在浏览器控制台执行
getComputedStyle(document.documentElement).getPropertyValue('--color-primary')，有返回值说明变量已注入 - 检查最终生成的 CSS 文件（如
dist/style.css），搜索.bg-primary或@media (min-width: 1920px)，没有就代表@theme未被解析 - VSCode 插件默认找
tailwind.config.js，删了它就得手动配置"tailwindCSS.experimental.configFile"指向含@import和@theme的主 CSS 文件
最容易被忽略的是：v4 中 tailwind.config.js 里的 theme.extend.colors 等字段完全不参与编译，哪怕文件存在、语法正确，也对类名生成零影响。你写的每一个 --color- 变量，都得亲手敲进 CSS 入口文件里，少一个字符，就少一个可用类。
