旧项目别急着升v4，新项目直接上v4——因v4的oxide引擎不识别@tailwind指令、需删指令改@import、移除postcss插件、theme.extend失效须用@theme规则、oklch色彩空间致rgb/hsl偏色、零配置依赖esm扫描但不处理字符串拼接等动态类名、content字段被忽略、编译更精准但漏配即缺失、strict模式下未定义css变量整条规则丢弃、调试降级因oxide为rust黑盒且无js溯源、intellisense需切预发布版，静默失效才是升级最大障碍。
旧项目别急着升 v4，新项目直接上 v4 —— 这不是拍脑袋的建议，而是由构建链路、配置兼容性和调试成本共同决定的硬约束。
旧项目升级 v4 会静默丢样式
v4 的 Oxide 引擎根本不认识 @tailwind base、@tailwind components 这些指令。它们不会报错，但 preflight 重置、表单默认样式、基础排版规则全都不生成，首页可能白屏或布局崩坏。
- 必须删掉所有
@tailwind指令，换成@import "tailwindcss" - 必须移除
postcss.config.js中的tailwindcss()插件，否则和 Vite 插件冲突，导致样式被跳过或重复处理 -
tailwind.config.js里的theme.extend已失效，得改用 CSS@theme规则，且语法不兼容 JS 对象写法 - 颜色值若仍用
rgb(255, 0, 0)或hsl(0, 100%, 50%)，在 v4 默认 OKLCH 色彩空间下渲染可能偏色
v4 的“零配置”只对标准项目成立
所谓自动 content 扫描，依赖构建工具（如 Vite）劫持 ESM 模块图的能力。它能识别 .vue 的 <template></template>、.mdx 里的 JSX 字符串、Astro 的 frontmatter，但对以下情况无能为力：
- 字符串拼接类名：
className={`bg-${color}-500`}—— v4 不解析运行时表达式，这类动态类名直接不生成 - 非标准路径引入的模板文件（比如用
fs.readFileSync加载的 HTML 片段） - 没走 ESM import 链的文件（如通过 Webpack require.context 动态加载的组件）
- 你还在
tailwind.config.js里留着content字段？它会被完全忽略，删掉更干净
v4 编译产物更小，但前提是 content 配得准
v4 不是“压缩得更好”，而是“根本不多生成”。v3 的 JIT 会先构造全部工具类再剔除未用项；v4 的 Oxide 只扫描匹配到的文件，没出现的 text-lg 连声明都不会写进 CSS。
- 漏配
.astro或.svelte文件路径 → 对应页面所有 Tailwind 类名都缺失 - 误配宽泛路径如
./src/**/*→ 扫描变慢，增量构建优势打折扣 - 自定义 CSS 里写了
calc(100% - var(--x))但--x未定义 → v3 宽容跳过，v4 在 strict 模式下整条规则静默丢弃 - 想放宽限制？可在 config 里加
lightningcss: { drafts: { nesting: true } }，但会牺牲 tree-shaking 精度
调试体验降级是真实代价
v3 的 JIT 是 JS 实现，DevTools 里能看到“哪段 JS 生成了 .bg-blue-500”，方便断点追踪；v4 的 Oxide 是 Rust 编译的黑盒，DevTools 只显示最终 CSS，无法反查来源。
- 类名没生效？别指望看 JS 调用栈，得回溯 content 路径、检查字符串字面量是否被正确扫描
- 样式冲突难定位？v4 不再保留
@layer base/@layer components的原始结构，合并后的规则选择器更紧凑，但也更难对应到原始配置 - VSC IntelliSense 插件需手动切换到预发布版，否则补全提示可能滞后或缺失新语法
真正卡住升级的，从来不是性能数字，而是那些没报错、没警告、却让按钮突然没 hover 效果、让颜色悄悄变灰的静默失效点。v4 不是“更好用的 v3”，它是另一套构建契约 —— 接受它，就得重写配置逻辑、重审 content 覆盖面、重新适应调试方式。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
