Tailwind CSS v4 升级笔记

Tailwind CSS v4.0 正式发布后，我把一个小项目从 v3 升了上去。整体比预想顺利，但有几处改动不看文档很难发现，记在这里。

先跑官方升级工具

官方提供了一个自动迁移工具，会改依赖、改配置、改模板里的类名：

npx @tailwindcss/upgrade

建议在干净的 Git 工作区里跑，改完用 diff 逐个看一遍。下面几节是我看 diff 时记下的。

配置搬进 CSS

入口文件

v3 的三条指令变成了一行导入：

/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import "tailwindcss";

主题变量

自定义颜色、字体不再写在 tailwind.config.js 里，而是用 @theme 声明 CSS 变量：

@import "tailwindcss";

@theme {
  --color-sakura: oklch(0.82 0.08 0);
  --font-display: "Noto Serif SC", serif;
}

声明之后，bg-sakura、font-display 这些类就能直接用，同时 var(--color-sakura) 也可以在任何地方引用。

暂时保留旧配置

如果一时迁不完，可以用 @config 继续加载 JS 配置文件：

@config "../../tailwind.config.mjs";

构建集成

用 Vite 的项目改用官方插件，比走 PostCSS 简单：

import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [tailwindcss()],
});

另外 v4 会自动检测模板文件，不再需要 content 数组。如果有文件在默认扫描范围之外，用 @source 补上。

改了名字的工具类

升级工具大部分能自动改，但我还是在几个动态拼接的类名上漏了：

还有两处默认值的变化：ring 的默认宽度从 3px 变成了 1px，border 的默认颜色变成了 currentColor。页面上突然多出来的深色边框，基本都是后者导致的。

小结

升级本身花了一个晚上，大部分时间在逐页对比样式。如果你的项目也有用字符串拼接出来的类名，记得手动搜一遍。