Tailwind CSS v4 alpha 用 Rust 的 Oxide 引擎将增量构建提速至 5ms，@import 'tailwindcss' 替代 @tailwind 指令，主题配置迁移至 @theme CSS 规则，content 路径需手动补全非标准文件。
现在就用 Tailwind CSS v4 alpha 版本，不是为了赶时髦，而是因为它的底层已经不可逆地变快了——Rust 写的 Oxide 引擎让增量构建从 44ms 降到 5ms，无新增变更甚至压到 192µs。这个量级的延迟，已经逼近人眼和手指的感知下限。
为什么 @import 'tailwindcss' 必须替代 @tailwind 指令
v4 彻底移除了 PostCSS 插件链，@tailwind base 这类写法不再被识别，也不会报错，只会静默失效——你改了 class，样式就是不出现，排查时容易绕进 HTML 或 JS 逻辑里浪费时间。
- 旧写法必须全部删掉，包括注释里的残留；
-
@import 'tailwindcss'是唯一入口，它自动展开 base / components / utilities 三层； - 如果你用 Vite，还需确认
tailwindcss()插件已注册在vite.config.js的plugins数组中，否则@import不会被处理； - Lightning CSS 对语法更严格，比如不允许未闭合的括号或非法嵌套，会直接中断构建，而不是跳过。
主题配置从 tailwind.config.js 迁移到 @theme CSS 规则的实际影响
以前靠 JS 对象定义颜色、间距，现在全靠 CSS 变量 + @theme 块，好处是热更新时变量修改立刻生效，坏处是 IDE 不再能跳转到配置项，也失去 JS 层的类型提示和计算能力（比如动态生成色阶）。
- 颜色必须用 OKLCH 格式（如
--color-primary-500: oklch(60% 0.3 280)），HEX 或 RGB 会被忽略； -
@theme必须写在@import 'tailwindcss'之前，否则变量不生效； - 自定义间距、圆角等仍支持数值映射，但不能写函数（如
calc()）或引用其他变量； - 暗色模式默认启用，
dark:前缀类直接可用，无需配置darkMode字段。
content 路径自动检测在哪些场景下会漏掉文件
自动扫描依赖 .gitignore 规则，所以被忽略的模板文件（如 src/dev/*.html 或临时生成的 dist/*.svelte）根本不会被纳入工具类生成范围——结果就是 class 写对了，CSS 却没生成。
立即学习“前端免费学习笔记（深入）”；
- 如果项目有非标准后缀的模板（如
.vue.html或.astro），需手动加到content数组里； - Vite 插件默认只扫描
src和index.html，若组件在packages/或libs/下，得显式声明路径； - SSR 或服务端渲染的字符串模板（如
res.send("<div class='text-red-500'>")）完全无法被检测，这类 class 必须手动保留在content中。
真正卡住人的从来不是“要不要升级”，而是迁移后某几个 class 突然失效，却查不到原因——v4 的静默失败机制、CSS 变量作用域限制、以及 Lightning CSS 的语法洁癖，都要求你把“哪里可能出问题”的清单刻进肌肉记忆里。
