Tailwind CSS v4 因改用 Rust 的 Oxide 引擎而完全弃用 tailwind.config.js，仅通过 @import "tailwindcss" 入口指令启用 JIT、三层加载及 important 语法，同时移除 @tailwind 指令族、绕过 PostCSS 插件链，并要求 @theme 必须为符合前缀规范的静态 CSS 自定义属性且置于 @import 之前。
tailwind.config.js 为什么完全失效
因为 Tailwind CSS v4 底层改用 Rust 编写的 Oxide 引擎，它不解析 JS 配置文件，只扫描 CSS 源码中的 @import、@theme、@utility 等指令。即使你保留 tailwind.config.js，它也不会被读取，也不会报错——静默忽略。
常见错误现象：
-
theme.extend里定义的colors或spacing不生成对应工具类（如text-brand） -
content字段写了但新组件目录里的类名就是不编译出来 -
important: true配置无效，!text-red-500依然不生效
真正起作用的是这行：@import "tailwindcss" —— 它不是普通导入，而是 Oxide 的入口指令，自动启用 JIT、加载三层、隐式支持 important 语法等。
@tailwind base 为什么突然不工作了
v4 彻底移除了 @tailwind 指令族（@tailwind base、@tailwind components、@tailwind utilities）。它们不再被识别，也不会报错，只会跳过——结果就是 CSS 文件里什么都没输出，浏览器里看不到任何 Tailwind 类。
立即学习“前端免费学习笔记（深入）”；
必须替换成：
- 删掉所有
@tailwind *行 - 在独立 CSS 文件（如
src/styles/tailwind.css）最顶部写@import "tailwindcss" - 确保该文件是构建链路中第一个被处理的 CSS 入口（不能嵌套在
@layer或其他规则里）
如果还混着用，比如 @layer base { @tailwind base }，Oxide 引擎会直接跳过整块，连警告都没有。
PostCSS 插件链为什么被绕过了
v4 的 tailwindcss() Vite 插件（或 Webpack/ESBuild 对应插件）已接管全部样式流程：从源码扫描、类名提取、JIT 编译到 CSS 输出，全程不经过 PostCSS。所以 postcss.config.js、autoprefixer 插件、甚至手动调用 postcss CLI 都不再参与 Tailwind 样式生成。
容易踩的坑：
- 在
vite.config.ts中同时启用postcss()和tailwindcss()→ 导致重复处理，hover:、dark:等变体失效 - 显式安装
autoprefixer并配置前缀 → 反而可能覆盖 Oxide 内置的正确前缀逻辑 - 以为
postcss.config.js还能控制 Tailwind 行为 → 实际上它只影响非 Tailwind 的 CSS 处理（比如你自己写的.legacy-card）
@theme 为什么不能写成 JS 对象格式
v4 的 @theme 是原生 CSS 规则块，不是 JS 配置的搬运。它只认带标准前缀的 CSS 自定义属性，且值必须是静态字面量。
这些写法会失效：
-
--color-primary: #3b82f6（缺oklch()格式，v4 默认要求 OKLCH） -
--spacing-8: calc(2rem)（不支持函数） -
--font-sans: var(--base-font)（不支持变量引用） -
@theme { colors: { primary: '#3b82f6' } }（这不是合法 CSS，Oxide 直接跳过）
正确写法是：@theme { --color-primary-500: oklch(60% 0.3 280); --font-sans: 'Inter', sans-serif; } —— 变量名必须以 --color-、--font-、--spacing- 开头，否则引擎不会映射为工具类。
最常被忽略的一点：@theme 必须写在 @import "tailwindcss" 之前，顺序反了变量就不可见；而且它只作用于当前 CSS 文件，跨文件不继承——想全局生效，得每个入口 CSS 都写一遍，或者用 @layer rules 统一收口。
