不能平滑升级。v4构建机制、配置模型和扫描逻辑与v3本质不同，旧项目直接升级会静默丢样式；必须删除所有@tailwind指令、移除postcss.config.js中tailwindcss()插件、改用@import"tailwindcss";和@source规则，并手动添加@custom-variant dark。
不能平滑升级。v4 的构建机制、配置模型和扫描逻辑与 v3 本质不同，旧项目直接升级大概率会静默丢样式——不是报错，而是页面白屏、暗色模式失效、hover:类不生效、text-xl等基础类消失。
必须删除所有 @tailwind 指令
v4 的 Oxide 引擎完全不识别 @tailwind base、@tailwind components、@tailwind utilities。它们不会报错，但 preflight 重置、表单默认样式、工具类全都不生成。
- 找到所有 CSS/SCSS 入口文件（如
src/styles/main.css），删掉全部三行@tailwind指令 - 替换成单行：
@import "tailwindcss"; - 如果用了
@layer自定义层，确保它写在@import之后，否则会被忽略
必须移除 postcss.config.js 中的 tailwindcss() 插件
v4 默认走 Lightning CSS 流程，若 postcss.config.js 里还留着 tailwindcss()，会和 Vite 或 Angular 的内置处理冲突，导致样式被跳过或重复编译。
- 打开
postcss.config.js，删掉tailwindcss()这一行（保留autoprefixer可选） - Angular 项目还需检查
angular.json中是否手动启用了 PostCSS；如有，应禁用或确认使用的是@tailwindcss/postcss - Vite 用户要卸载
tailwindcss的 PostCSS 插件，改用官方第一方插件@tailwindcss/vite
dark: 类和 @apply 会直接失效
v4 移除了 darkMode: 'class' 配置项，也不再自动解析 dark: 前缀；@apply 在默认 Lightning CSS 模式下不展开响应式/交互前缀。
- 在
@import "tailwindcss";后紧接一行：@custom-variant dark (&:where(.dark, .dark *));（注意必须带:where()，否则权重爆炸） - HTML 根元素仍需有
class="dark"，不依赖 JS 初始化 -
@apply hover:bg-blue-500 md:p-4→ 编译后只剩bg-blue-500 p-4；改用原生嵌套：.btn { &:hover { @apply bg-blue-600; } @media (min-width: 768px) { @apply p-4; } }，并确保构建链支持 CSS Nesting
content 扫描路径必须显式覆盖所有模板文件
v4 的“零配置”只对标准 ESM 导入路径有效。字符串拼接类名（className={`bg-${color}-500`}）、.astro、.svelte、动态 require.context 等场景，v4 完全无法推断，必须手动列进 content。
- 删掉
tailwind.config.js里的content字段（它已被忽略） - 改用 CSS 中的
@source规则，例如：@source "./src/**/*.{vue,tsx,astro}"; - 路径必须用双引号包裹，glob 语法要合法；
./src/**/*.vue❌，"./src/**/*.vue"✅ - 若项目含 MDX、SvelteKit
+layout.svelte、Next.js App Router 的layout.tsx，这些路径一个都不能漏
最危险的不是报错，而是没报错却漏了 @source 路径或忘了加 @custom-variant —— 页面看起来“差不多”，但交互状态、暗色模式、响应式断点全在关键时刻掉链子。建议升级后逐页检查 hover/focus/dark/md/lg 等变体的实际渲染效果，别信“看起来正常”。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
