从 Tailwind CSS v3 迁移到 v4

为什么要迁移

Tailwind CSS v4 把配置从 JavaScript 搬到了 CSS，构建更快、写法更统一。如果你有 v3 项目想升级，主要改动集中在配置、指令和主题命名上。本篇给出一份速查清单。

配置与指令的变化

配置方式变化

v3 用 tailwind.config.js 的 theme 字段定义设计令牌：

// v3 tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: "#4f46e5",
      },
    },
  },
}

v4 改为在 CSS 里用 @theme：

/* v4 style.css */
@import "tailwindcss";

@theme {
  --color-brand: #4f46e5;
}

迁移要点：把 colors.brand 改成 --color-brand，fontFamily、spacing 等以此类推，变量名前缀对应 --color-、--font-、--spacing-。

@import 替代 @tailwind

v3 在 CSS 顶部写三条指令：

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

v4 统一成一行：

/* v4 */
@import "tailwindcss";

content 数组被 @source 替代

v3 在配置里用 content 指定扫描目录：

// v3
module.exports = {
  content: ["./src/**/*.{html,js}"],
}

v4 默认自动扫描项目文件，无需配置。如果某些目录没被扫到，用 @source 显式声明：

@import "tailwindcss";

@source "./src";
@source "./templates/**/*.html";

@source 还能用 ! 排除路径，比如 @source !./dist。

命名与变体的变化

颜色与阴影命名微调

部分默认令牌在 v4 中重命名，迁移时注意替换：

• 圆角 rounded-sm 等层级整体调整，rounded 现在等于 v3 的 rounded-md
• 阴影默认改用更柔和的 --shadow-* 变量，shadow-sm 视觉更轻
• 部分颜色明度档位重新校准，若用了具体色值（如 blue-500）建议肉眼核对一遍

@custom-variant 替代插件式 dark

v3 常用 darkMode: "class" 或插件来开深色模式：

// v3
module.exports = {
  darkMode: "class",
}

v4 用 @custom-variant 自定义 dark 的触发条件：

@import "tailwindcss";

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

如果想跟随系统偏好，可以用媒体查询版本：

@custom-variant dark (&:media(prefers-color-scheme: dark));

已删除或改动的点速查

• 不再需要 tailwind.config.js（除非想用 @config 保留旧配置）
• @tailwind 三条指令废弃，改用 @import "tailwindcss"
• content 选项移除，改由 @source 或自动扫描
• darkMode 配置项移除，改由 @custom-variant dark 定义
• 默认边框色从 gray-200 改为 currentColor，需要时显式写 border-gray-200
• 部分工具类重命名，建议跑一遍构建并比对页面效果

迁移步骤建议

1. 安装 v4 包并移除 v3 的 PostCSS 插件配置
2. 把 tailwind.config.js 的 theme 翻译成 @theme 变量
3. CSS 里 @import "tailwindcss" 替换 @tailwind 指令
4. 用 @source 确认扫描范围，必要时补充
5. 用 @custom-variant dark 重建深色模式
6. 构建并逐页核对样式差异