Tailwind CSS v4升级不能仅改版本号，必须重写配置：用@import "tailwindcss"替代@tailwind指令，@theme定义主题，@custom-variant重写暗色模式，插件改用@plugin导入，且content字段仍需保留在tailwind.config.js中。
直接升级会失败，因为 v4 不是 v3 的“增强版”，而是用 Rust 重写的全新引擎（Oxide），配置逻辑、构建方式、插件系统全部重构。不能只改版本号，必须按新范式重写关键部分。
tailwind.config.js 变成可选，但 content 字段仍要保留
v4 的 Oxide 引擎默认不读 tailwind.config.js，它只扫描 CSS 文件里的 @import "tailwindcss" 和 @theme 指令。但 content 路径仍需在 JS 配置里声明，否则开发时无法检测 HTML/JSX 中用到的类名。
- 如果你项目里已有
tailwind.config.js，保留它，只留content字段（其他如theme、plugins在 v4 中基本失效） - 示例最小配置：
module.exports = { content: ["./src/**/*.{js,jsx,ts,tsx}", "./public/**/*.html"] } - 不要在
theme.extend.colors里定义颜色——v4 要求用@theme { --color-primary: #3b82f6; }写在 CSS 文件中
@import "tailwindcss" 替代三行 @tailwind 指令
v3 的 @tailwind base、@tailwind components、@tailwind utilities 全部废弃。v4 只需一行 @import "tailwindcss"，它会自动注入所有层（base / components / utilities）。
- 把旧的
src/index.css或src/input.css中这三行删掉：@tailwind base; @tailwind components; @tailwind utilities;
- 替换成：
@import "tailwindcss";
- 如果用了插件（如
@tailwindcss/forms），现在要写成：@import "tailwindcss"; @plugin "@tailwindcss/forms";
darkMode 必须用 @custom-variant 重写
v3 的 darkMode: 'class' 在 v4 中完全无效。v4 不再内置暗色模式变体，必须手动声明 @custom-variant dark，且要配合 :where() 防止样式优先级爆炸。
立即学习“前端免费学习笔记（深入）”；
- 删除
tailwind.config.js中的darkMode字段 - 在你的主 CSS 文件（如
src/index.css）顶部添加：@custom-variant dark (&:where(.dark, .dark *));
- 之后
dark:bg-black、dark:text-white才能正常工作 - HTML 根元素仍需加
class="dark"，和 v3 一样
插件必须用 @plugin 导入，且版本要对齐
v4 插件接口彻底重写，v3 插件（如 @tailwindcss/forms@^0.5）在 v4 下直接报错或静默失效。所有插件必须升级到 v4 兼容版，并用 @plugin 声明。
- 安装命令要改：
yarn add -D @tailwindcss/forms@latest（不是@tailwindcss/formsv0.x） - 导入方式必须是 CSS 指令：
@plugin "@tailwindcss/forms";，不能写在 JS 配置的plugins数组里 - 常见插件 v4 版本号：
@tailwindcss/forms@^1.0.0、@tailwindcss/typography@^1.0.0、@tailwindcss/aspect-ratio@^1.0.0 - 如果你用的是
@tailwindcss/postcss，它已废弃；v4 不走 PostCSS 流程，CLI 直接调用 Oxide 引擎
v4 最容易被忽略的点是：你以为只是换了个构建工具，其实整个样式生成模型都变了——主题靠 CSS 变量、变体靠 @custom-variant、插件靠 @plugin、内容检测靠 @import 后的静态分析。任何试图“兼容保留旧写法”的折中方案，都会在某次构建后突然失效。
