2. v4 新特性概览：与 v3 的重大差异

本节目标：搞清楚 v4 到底改了什么，哪些 v3 写法已经过时，上手直接用新姿势。

如果你之前用过 v3，这一章帮你快速对齐。如果是全新接触，也可以先扫一眼，后面遇到概念再回来翻。

最大的变化：配置文件没了

v3 时代，你会有一个 tailwind.config.js，里面写 content、theme、plugins：

// 这是 v3 写法，v4 已废弃
module.exports = {
  content: ['./src/**/*.{html,js}'],
  theme: {
    extend: {
      colors: { brand: '#316ff6' }
    }
  }
}

v4 默认不需要这个文件了。配置直接写在 CSS 里，用 @theme 指令：

@import "tailwindcss";

@theme {
  --color-brand: #316ff6;
}

这就是 CSS-first 配置。你的设计令牌（design token）全在 CSS 里定义，不需要额外维护一个 JS 文件。

v3 的 CSS 文件长这样：

@tailwind base;
@tailwind components;
@tailwind utilities;

v4 变成了一行：

@import "tailwindcss";

简洁多了。如果你想分层控制，也可以单独引入：

@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css" layer(utilities);

v3 要在 config 里手动写 content 数组告诉 Tailwind 扫哪些文件。v4 不用了——它会自动扫描项目源文件。

哪些文件会被扫？除了 .gitignore 里的、node_modules、二进制文件、CSS 文件本身，其他都扫。

如果想手动指定或排除，用 @source 指令：

@import "tailwindcss";
@source "../node_modules/@acmecorp/ui-lib";
@source not "../src/components/legacy";

v4 底层用 Rust 重写了，叫 Oxide 引擎，基于 Lightning CSS。构建速度比 v3 快很多。

对你来说，这意味着 npm run dev 启动更快、热更新更及时。不需要改任何代码，白嫖的速度提升。

v3 在 config 里写 darkMode: 'class' 或 'media'。v4 默认跟随系统（prefers-color-scheme），想手动切换用 @custom-variant：

@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

然后在 HTML 里给 <html class="dark"> 就能触发 dark:* 变体。

v4.2 起，start-* 和 end-* 开头的间距/定位类已废弃，改用逻辑属性命名：

旧类目前还能用但会报警告，未来版本会移除。

v4.3 是 2026 年 5 月发布的大版本，加了这些：

scrollbar 工具类：直接控制滚动条样式，不需要浏览器私有 API：

<div class="scrollbar-thin scrollbar-thumb-gray-400">

@container-size：创建尺寸容器，支持 block-size 查询：

<div class="@container-size">
  <div class="h-[50cqb]">

zoom-* / tab-*：直接映射 CSS zoom 和 tab-size 属性。

stacked / compound @variant：在 CSS 里嵌套多个伪状态或共享样式块。

font-features-*：控制 OpenType 字体特性：

<div class='font-features-["tnum"]'>

安装方式	v3	v4
Vite	`tailwindcss` + `postcss` + `autoprefixer`	`@tailwindcss/vite` 插件
PostCSS	`tailwindcss` 插件	`@tailwindcss/postcss` 插件
CLI	`npx tailwindcss`	`npx @tailwindcss/cli`
CDN	`<script src="cdn.tailwindcss.com">`	`<script src="cdn.jsdelivr.net/npm/@tailwindcss/browser@4">`

Warning

网上很多教程（包括菜鸟教程部分文章）还在讲 v3 写法。看的时候留个心眼，认准 @import "tailwindcss"; 这个入口才是 v4。

下一章我们进入实战，把 Tailwind 装到项目里。