Tailwind CSS v4 将样式生成逻辑重建于 CSS 自定义属性之上，@theme 声明的变量是真实参与渲染的输入源而非辅助配置；其必须位于 @import 'tailwindcss' 之前，否则变量未声明导致工具类失效，且仅 OKLCH 等新色彩空间值被识别。
Tailwind CSS v4 不是“用 CSS 变量辅助配置”，而是把整个样式生成逻辑重建在 CSS 自定义属性之上——@theme 声明的变量不是“配置项”，而是真实参与渲染的 CSS 层级输入源。
为什么 @theme 必须写在 @import 'tailwindcss' 之前
Oxide 引擎扫描 CSS 文件时，按源码顺序解析指令；@import 'tailwindcss' 展开后会立即生成工具类（如 text-primary），而这些类的值依赖 --color-primary 等变量。如果 @theme 在它之后，变量尚未声明，引擎就只能 fallback 到默认值或静默忽略。
- 实际现象：写了
--color-primary: #3b82f6，但text-primary没生效，控制台也无报错 - 检查顺序：打开构建后的 CSS，搜索
text-primary，看它的声明是否引用了var(--color-primary)；没引用说明@theme位置错了 - Vite 用户额外注意：
tailwindcss()插件必须在css.preprocess阶段前注册，否则@import不会被识别
--color-primary 为什么不能用 HEX 或 RGB
v4 的 Oxide 引擎只识别 OKLCH、HWB、LCH 等新色彩空间格式的自定义属性值，HEX 和 RGB 被视为“非主题变量”，直接跳过映射。
- 错误写法：
--color-primary: #3b82f6;→text-primary不生成 - 正确写法：
--color-primary: oklch(60% 0.3 280);（推荐用 OKLCH Picker 生成） - 兼容旧色值：可用
oklch(from #3b82f6 l c h)，但需确保构建工具支持 CSSfrom语法（Lightning CSS 默认支持） - 字体、间距等变量不受限，仍可写
--font-sans: 'Inter', sans-serif;或--spacing-4: 1rem;
@utility 替代 addUtilities 后，哪些 JS 逻辑必须剥离
v4 的 @utility 是纯 CSS 声明，不执行 JS 表达式，也不支持动态计算。所有依赖运行时逻辑的样式注入都得提前转为静态 CSS 规则。
立即学习“前端免费学习笔记（深入）”；
- 无法再做：
addUtilities({ '.animate-bounce-slow': { animation: `bounce ${duration}s` } })——${duration}是 JS 变量，@utility不解析 - 可行替代：
@utility animate-bounce-slow { animation: bounce 1.5s; }，或用响应式变体：@lg @utility animate-bounce-slow { animation-duration: 1.5s; } - 条件类（如 dark/light）必须显式写出：
@dark .bg-card { background-color: var(--color-gray-800); }，不能靠 JS 判断环境 - 插件中调用
addUtilities的代码可保留，但仅用于兼容模式（不推荐）；生产构建应完全迁移到 CSS 层
最容易被忽略的是变量作用域——@theme 块里的 --color-primary 只在当前 CSS 文件内有效，跨文件复用需靠 :root 显式提升，或者统一入口文件集中声明。否则你会在某个组件里改了颜色，另一个页面却还是旧值。
