Tailwind CSS v4 初体验

Tailwind v4 把配置从 tailwind.config.js 挪进了 CSS：用 @theme 定义颜色、间距等，用 @layer 组织，和 PostCSS/Vite 的集成方式也有变化。第一次用会有点「找不到 config 文件」的不习惯，但习惯之后改主题确实更直观。

和 v3 的差异

• 主题：不再依赖 JS 的 theme.extend，而是在 CSS 里写 @theme { --color-xxx: ... }，和设计 token 的思路更接近。
• 插件：生态还在过渡，部分 v3 插件要等 v4 兼容或替代方案。
• 性能：构建和 HMR 在我这边体感更快，官方也强调过引擎重写。

实际迁移改了什么

本站从 v3 搬到 v4，改动集中在三处，比预想的小：

1. 颜色变量改名了。 v4 默认带一套新的命名空间，比如 --color-bg、--color-fg、--color-border，直接在 @theme 里声明就能用 bg-bg、text-fg、border-border。v3 那种在 theme.extend.colors 里嵌对象写法没了，改成 CSS 变量后 IDE 的跳转和补全反而更顺。

@theme {
  --color-bg: #050505;
  --color-fg: #f5f5f5;
  --color-border: oklch(1 0 0 / 0.1);
}

2. 入口文件变了。 不再需要在 JS 配置里指 content 数组，v4 自动扫描。但要在 CSS 顶部加一行，告诉它「这是 Tailwind 入口」：

@import "tailwindcss";

少了 tailwind.config.ts 这个文件，第一反应是「配置去哪了」——其实在 global.css 里。

3. 阴影 / 圆径的旧工具类换了写法。 shadow-sm 之类在 v4 里的尺度名变了（shadow-sm → shadow-xs 这种偏移），迁移时全局替换，但不留神会漏掉几处。

一个踩到的坑

@theme 里定义的颜色，默认会被生成为 :root 下的 CSS 变量。如果之后想用 dark: 做深浅色切换，不能只在 @theme 里改——变量是静态的。要么把变量定义搬到 @layer base 里、用 :root / .dark 分别声明，要么干脆用 data-theme 属性切换。本站本来就是单一深色主题，没踩到这个，但打算做明暗切换的话要提前想清楚。

适合谁

如果你是新开项目、且不依赖一堆 Tailwind 插件，直接上 v4 没问题。老项目可以等常用插件都支持了再迁，或者先在侧枝分支试跑一遍——核心类名大多没变，主要工作量在主题变量和入口文件这两处。