Tailwind CSS v4 指南：新引擎与 CSS-first 配置

Tailwind CSS v4 指南：新引擎与 CSS-first 配置

Tailwind CSS v4 是框架的一次从零重写：官方基准测试显示，全量构建提速 3.5 倍以上，增量构建提升 8 倍以上，而"未产生新 CSS"的增量构建甚至可以快上百倍、以微秒计。对建站团队来说，这意味着大型项目也能保持近乎即时的样式反馈——保存文件、刷新页面，改动几乎同步出现，开发手感接近"无构建"。

v4 的改动不是小修小补，而是把"配置"这个心智负担从 JS 迁移到了 CSS：不再需要 tailwind.config.js、不再维护 content 数组，主题变量、断点、自定义颜色全部写进 CSS 本身。下面从新引擎、安装、配置到升级，把 v4 的关键变化拆开讲清楚。

Tailwind 相关模板可参考本站Tailwind 页面模板，也属于前端搭建分类下的主流样式方案。

一、新引擎与现代 CSS

v4 充分利用了现代 CSS 能力：原生级联层（@layer）更精细地控制样式优先级、@property 注册自定义属性（可动画化渐变）、color-mix() 让任意颜色（包括 CSS 变量与 currentColor）都能调透明度、逻辑属性简化 RTL 支持并减小生成体积。同时默认调色板从 rgb 全面升级到 oklch，色彩更鲜艳。

这些特性带来的实际收益很具体：以渐变为例，v3 里 bg-gradient-to-r 只能做线性渐变，v4 用 bg-linear-to-r、bg-radial、bg-conic 分别覆盖线性、径向和锥形渐变；配合 color-mix()，你甚至能直接给 currentColor 调透明度，很多过去需要写自定义 CSS 的配色场景现在一行工具类就够。

二、简化安装

v4 把安装压缩到"三条命令"：安装 tailwindcss 与 @tailwindcss/postcss，添加 PostCSS 插件，然后在 CSS 里写一行 @import "tailwindcss"。不再需要 @tailwind 指令、tailwind.config.js 或 content 数组——模板文件通过启发式自动检测（自动忽略 .gitignore 与二进制文件），必要时可用 @source 指令补充来源。

以最常见的 Vite 项目为例：

npm install tailwindcss @tailwindcss/vite

在 vite.config.js 里注册插件，然后在入口 CSS 里 @import "tailwindcss"，就完成了整个接入。对比 v3 的 tailwind.config.js + postcss.config.js + @tailwind base/components/utilities 三连，配置项少了一大半。

三、CSS-first 配置与主题变量

配置从 JS 迁移到 CSS：在 @theme 中定义设计令牌即可扩展间距、颜色、断点与字体。

@import "tailwindcss";

@theme {
  --color-avocado-500: oklch(0.84 0.18 117.33);
  --breakpoint-3xl: 1920px;
  --font-display: "Satoshi", "sans-serif";
}

所有设计令牌默认生成对应的 CSS 变量，运行时可直接引用，也可传给动画等第三方库。这意味着"设计系统"和"代码"真正共用同一套变量：设计师给一个色值，开发者把它写进 @theme，整个项目的按钮、边框、渐变都会跟着走。

四、动态工具类与变体

间距类（px-*、mt-*、w-*）现在由单一 --spacing 变量动态推导，任意数值开箱即用，如 w-17、grid-cols-15。新增容器查询（@container/@sm:）、not-* 变体、starting（配合 @starting-style 做入场动画）、3D 变换（rotate-x-*、perspective-*）与更丰富的渐变 API（bg-linear-*、锥形/径向渐变）。此外还内置 color-scheme、field-sizing、inset-shadow-* 等实用工具。

容器查询尤其值得关注：它让组件可以根据"自己所在容器"的宽度而不是视口宽度来响应，写卡片、侧边栏这类可复用组件时，比媒体查询自然得多。一个 @container 加一个 @md:flex-col，就能让同一套组件在窄容器里自动换行堆叠。

五、与构建工具集成

Vite 用户可直接使用官方 @tailwindcss/vite 插件，比 PostCSS 方式更快、配置更少（详见Vite 构建工具指南）。v4 也内置 @import 支持，无需 postcss-import 即可合并多个 CSS 文件。Webpack、Rollup、Svelte、Remix、Nuxt 等生态也都有对应的官方或社区接入方式，迁移路径基本是"换掉旧插件、改一行 import"。

六、从 v3 升级

官方提供了自动化升级工具与升级指南：先跑 npx @tailwindcss/upgrade 处理大部分改动，再人工检查被重命名的类（如 bg-gradient-* → bg-linear-*）、被移除的配置项与阴影/边框默认值变化。

升级时最容易踩的坑有三个：一是项目里用到了被移除的旧工具类（比如 flex-shrink-0 改为 shrink-0 后的旧写法）；二是自定义主题写在 tailwind.config.js 里、没迁移到 @theme，导致类名全部失效；三是 @import 顺序改变后，原有 CSS 的层叠结果和以前不一样。建议升级后跑一遍视觉回归，重点核对按钮、阴影、边框这些样式敏感区域。响应式页面结构可参考响应式导航模板与HTML 页面模板。

七、v3 与 v4 关键差异

常见问题

升级后样式全乱？ 优先检查是否还有残留的 tailwind.config.js 配置没迁移到 @theme，以及项目里是否混用了 v3 和 v4 的插件。

某个类没生效？ 确认文件是否被自动内容检测覆盖；如果文件在 node_modules 或 .gitignore 内，需要用 @source 手动声明。

原文来源：https://tailwindcss.com/blog/tailwindcss-v4；升级指南：https://tailwindcss.com/docs/upgrade-guide