Tailwind CSS 4 换了套配置方式

从 JS 回到 CSS#

Tailwind v3 的项目根目录长这样：

tailwind.config.js   ← 主题、插件、content 扫描路径
postcss.config.js
app/globals.css      ← @tailwind base; @tailwind components; @tailwind utilities;

v4 之后只剩一个文件：

@import "tailwindcss";

@theme {
  --color-brand-500: #e4513a;
  --font-sans: "PingFang SC", "Microsoft YaHei", sans-serif;
}

三个 @tailwind 指令合并成了 @import "tailwindcss"， 而所有的主题变量变成了标准的 CSS 自定义属性，写在 @theme 里。

一个颜色，一整套色阶#

定义 --color-brand-500 之后，Tailwind 会自动生成 bg-brand-500、 text-brand-500、border-brand-500、ring-brand-500 等等。 色阶命名和内置颜色完全一致：

@theme {
  --color-brand-50: #fff2ef;
  --color-brand-100: #ffe1da;
  --color-brand-200: #ffc5b8;
  --color-brand-300: #fb9e8a;
  --color-brand-400: #f2715a;
  --color-brand-500: #e4513a;
  --color-brand-600: #cb3823;
}

这个站点的 brand 是木棉红——广州的市花。选一个和自己有关系的颜色， 比从调色板里随便挑一个更容易坚持下去。

深色模式不再依赖 config#

v3 里要先在 config 里写 darkMode: "class"。v4 用一条指令代替：

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

这行的意思是：当元素本身有 .dark，或者它在某个 .dark 祖先里面时， dark: 前缀的样式就生效。

<html class="dark">
  <body>
    <!-- 这里的 dark:bg-stone-900 会生效 -->
  </body>
</html>

自定义工具类#

v4 用 @utility 定义自己的工具类：

@utility no-scrollbar {
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}

写完之后 no-scrollbar 就能像内置类一样用，而且支持变体（md:no-scrollbar）。

我踩到的一个坑#

.article a 这类「作用域内的元素选择器」和工具类的优先级关系需要留意：

.article a { text-decoration: underline; }   /* 0-1-1 */

这时候在元素上加 no-underline（0-1-0）是压不过它的， 得用 !no-underline 或者把选择器写成 .article .heading-anchor（0-2-0）。

我一开始就是在这里卡了十分钟——标题旁边的 # 锚点死活去不掉下划线。

值得迁移吗#

如果你正在新起项目，直接用 v4，没有理由从 v3 开始。

如果是老项目，迁移的主要工作量在于：

1. @tailwind 三条指令换成 @import "tailwindcss"
2. tailwind.config.js 里的 theme.extend 搬进 @theme，命名规则从驼峰改成短横线
3. 检查有没有用到被移除的类名（比如 bg-opacity-* 这类，现在统一用 bg-black/50 的斜杠语法）

第三条是最容易漏的。建议先跑一遍构建，Tailwind 会明确报出哪些类名已经不存在了。