tailwind css v4 是用 rust 重写的 oxide 引擎，需弃用 tailwind.config.js 中 theme 等配置、@tailwind 指令和 darkmode，改用 @import、@plugin、@custom-variant 和 @theme 等 css 指令，并确保 content 字段保留以支持类名检测。
不能只改 package.json 里的版本号，v4 是用 Rust 重写的全新引擎（Oxide），配置逻辑、插件机制、暗色模式、颜色定义全部推倒重来。直接升级会编译成功但样式全丢——因为类名根本没生成。
tailwind.config.js 不再主导构建流程
v4 的 Oxide 引擎默认不读 tailwind.config.js，它只扫描 CSS 文件里的 @import "tailwindcss" 和 @theme 指令。但 content 字段仍必须保留在 JS 配置里，否则开发时无法检测 HTML/JSX 中用到的类名。
- 保留
tailwind.config.js，但只留content字段，删掉theme、plugins、darkMode等所有其他配置 - 最小可用配置示例：
module.exports = { content: ["./src/**/*.{js,jsx,ts,tsx}", "./public/**/*.html"] } - 如果你用的是 Django Tailwind 或 Vite 插件，确认它们已适配 v4 —— 旧版插件可能仍试图读取废弃字段，导致静默失效
@tailwind 指令全部废弃，改用 @import
v3 的三行 @tailwind base、@tailwind components、@tailwind utilities 在 v4 中完全无效。v4 只需一行 @import "tailwindcss"，它会自动注入所有层级。
- 删掉旧 CSS 入口文件（如
src/index.css）里的三行@tailwind指令 - 替换成单行：
@import "tailwindcss"; - 如果用了插件（如
@tailwindcss/forms），必须紧接在@import后写：@plugin "@tailwindcss/forms"; -
@plugin必须带引号，且路径要和 npm 包名完全一致（比如不能写成@plugin "@tailwindcss/forms@latest"）
暗色模式必须手动声明 @custom-variant
v4 不再内置 dark: 变体，darkMode: 'class' 配置在 tailwind.config.js 里已彻底失效。漏配或错配会导致所有 dark:* 类在构建时被完全删除——DevTools 里搜不到对应 CSS 规则。
- 在主 CSS 文件顶部添加：
@custom-variant dark (&:where(.dark, .dark *)); - HTML 根元素仍需加
class="dark"，但切换必须操作document.documentElement.classList，body上加类无效 - 初始化脚本必须内联在
里、CSS<link>之前，用原生 IIFE，不能依赖DOMContentLoaded或框架生命周期 - 别碰
data-theme—— v4 的dark:只认.dark类或媒体查询，不识别自定义属性
颜色和主题必须写进 CSS，不能放 config.js
v4 废弃了 theme.extend.colors 这套 JS 配置方式。所有颜色、间距、字体等主题变量，必须用 CSS 自定义属性（--color-primary）在 CSS 文件中声明，并通过 @theme 指令注入。
- 删掉
tailwind.config.js里所有theme相关配置 - 在 CSS 入口文件中（
@import前）添加：@theme { --color-primary: #3b82f6; --spacing-4: 1rem; } -
@theme必须是顶层规则，不能嵌套在@layer或媒体查询里 - 若项目用了 CSS 变量做主题切换（如
--theme-color），v4 不会自动映射到工具类，得靠@apply或额外插件补位
最容易被忽略的是：v4 的构建过程不报错，但缺失关键指令（如 @custom-variant 或 @theme）时，对应类名压根不会出现在最终 CSS 里。别只看终端是否 success，一定要打开 DevTools 检查元素上是否有生成的样式规则。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
