Tailwind CSS v4 迁移指南

#css #tailwind #前端

v4 的核心变化

Tailwind CSS v4 是一次重大更新，最大的变化是：配置从 JavaScript 移到了 CSS。

不再需要 tailwind.config.js

在 v3 中，你需要这样的配置文件：

// tailwind.config.js (v3)
module.exports = {
  content: ["./src/**/*.{astro,html,js,jsx,md,mdx}"],
  theme: {
    extend: {
      colors: {
        primary: "#2563eb",
      },
    },
  },
  plugins: [],
};

v4 中，这一切都在 CSS 中完成：

@import "tailwindcss";

@theme {
  --color-primary: #2563eb;
}

自动内容检测

v4 不再需要配置 content 字段。它会自动扫描你的项目文件，通过 @import "tailwindcss" 的位置来判断扫描范围。

暗色模式

v3 默认的暗色模式是 media（跟随系统）。如果你需要用户手动切换（class-based），在 v4 中这样写：

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

这行代码告诉 Tailwind：当 HTML 元素上有 .dark class 时，启用暗色模式变体。

与 Astro 集成

在 Astro 项目中使用 Tailwind v4，只需要两步：

  1. 安装 @tailwindcss/vite 作为 Vite 插件
  2. 在全局 CSS 中 @import "tailwindcss"
// astro.config.mjs
import tailwindcss from "@tailwindcss/vite";

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

就这么简单。不需要 @astrojs/tailwind 集成包。

迁移建议

如果你有一个 v3 项目，迁移过程大致如下：

  1. 删除旧依赖：npm uninstall tailwindcss postcss autoprefixer
  2. 安装新依赖：npm install tailwindcss@latest @tailwindcss/vite@latest
  3. 删除 tailwind.config.js 和 postcss.config.js
  4. 在主 CSS 文件中添加 @import "tailwindcss"
  5. 将 theme.extend 中的自定义值迁移到 @theme {} 块
  6. 将插件配置迁移为 CSS 原生写法

大多数项目迁移不会超过 30 分钟。v4 的设计理念就是让 Tailwind 更像原生 CSS，减少配置层。

评论