11. v4 版本升级指南

1. 概述

Tailwind CSS v4 是一个重大版本更新，从 JavaScript 配置转向 CSS 优先的配置方式。

1.1 主要变化

变化	v3	v4
配置方式	`tailwind.config.js`	CSS 文件 (`@theme`)
安装方式	`postcss` + `tailwindcss`	`@tailwindcss/vite` 等
暗色模式	`dark:` 前缀	相同，但配置方式变化
自定义主题	`theme.extend`	`@theme` 块
插件	`plugins` 数组	`@plugin` 指令

2. 升级前的准备

2.1 检查当前版本

bash 复制代码

tailwindcss --version

2.2 备份项目

bash 复制代码

# 提交当前代码
git add .
git commit -m "备份：升级 Tailwind v4 前"

2.3 查看破坏性变更

官方升级指南
注意项目中使用的自定义配置

3. 升级步骤

3.1 卸载旧版本

bash 复制代码

npm uninstall tailwindcss postcss autoprefixer

3.2 安装 v4

bash 复制代码

# 根据项目类型选择
npm install @tailwindcss/vite   # Vite 项目
npm install @tailwindcss/cli    # CLI 项目
npm install @tailwindcss/postcss # PostCSS 项目

3.3 更新配置文件

Vite 项目

js 复制代码

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

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

PostCSS 项目

js 复制代码

// postcss.config.js
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

3.4 更新 CSS 文件

css 复制代码

/* 之前 (v3) */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* 之后 (v4) */
@import "tailwindcss";

3.5 迁移配置

颜色配置

css 复制代码

/* v3: tailwind.config.js */
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#6366f1',
      },
    },
  },
}

/* v4: src/index.css */
@import "tailwindcss";

@theme {
  --color-brand: #6366f1;
  --color-brand-light: #818cf8;
  --color-brand-dark: #4f46e5;
}

字体配置

css 复制代码

/* v3 */
theme: {
  extend: {
    fontFamily: {
      sans: ['Inter', 'system-ui'],
    },
  },
}

/* v4 */
@theme {
  --font-sans: 'Inter', system-ui, sans-serif;
}

断点配置

css 复制代码

/* v3 */
theme: {
  extend: {
    screens: {
      '3xl': '1920px',
    },
  },
}

/* v4 */
@theme {
  --breakpoint-3xl: 1920px;
}

间距配置

css 复制代码

/* v3 */
theme: {
  extend: {
    spacing: {
      '18': '4.5rem',
    },
  },
}

/* v4 */
@theme {
  --spacing-18: 4.5rem;
}

3.6 迁移插件

css 复制代码

/* v3: tailwind.config.js */
module.exports = {
  plugins: [
    require('@tailwindcss/typography'),
    require('@tailwindcss/forms'),
  ],
}

/* v4: src/index.css */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

3.7 迁移自定义插件

js 复制代码

/* v3: plugins/custom.js */
const plugin = require('tailwindcss/plugin');

module.exports = plugin(function({ addUtilities }) {
  addUtilities({
    '.text-gradient': {
      background: 'linear-gradient(135deg, #6366f1, #a855f7)',
      '-webkit-background-clip': 'text',
      'background-clip': 'text',
      color: 'transparent',
    },
  });
});

css 复制代码

/* v4: src/index.css */
@import "tailwindcss";

@utility text-gradient {
  background: linear-gradient(135deg, #6366f1, #a855f7);
  -webkit-background-clip: text;
  background-clip: text;
  color: transparent;
}

4. 常见迁移问题

4.1 类名不生效

问题：升级后某些类名不生效

原因：动态拼接的类名可能未被识别

解决：

jsx 复制代码

// ❌ 不生效
<div className={`text-${color}-500`}>

// ✅ 使用完整类名或映射
const colors = {
  red: 'text-red-500',
  blue: 'text-blue-500',
};
<div className={colors[color]}>

4.2 自定义主题不生效

问题：@theme 中的配置不生效

原因：语法错误或位置错误

解决：

css 复制代码

/* ✅ 正确位置：在 @import 之后 */
@import "tailwindcss";

@theme {
  --color-brand: #6366f1;
}

/* ❌ 错误：在 @import 之前 */
@theme {
  --color-brand: #6366f1;
}
@import "tailwindcss";

4.3 插件不兼容

问题：某些第三方插件还不支持 v4

解决：

检查插件是否发布 v4 兼容版本
临时用 @utility 替代
等待插件更新

4.4 PostCSS 配置问题

问题：postcss.config.js 格式变化

解决：

js 复制代码

// v3
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

// v4
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

5. 新特性使用

5.1 容器查询

css 复制代码

@import "tailwindcss";
@plugin "@tailwindcss/container-queries";

html 复制代码

<div class="@container">
  <div class="grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-3">
    <!-- 根据容器宽度响应 -->
  </div>
</div>

5.2 3D 变换

css 复制代码

@import "tailwindcss";
@plugin "tailwindcss-3d";

html 复制代码

<div class="preserve-3d rotate-x-45 rotate-y-30">
  3D 元素
</div>

5.3 自定义变体

css 复制代码

@custom-variant children (& > *);

/* 使用 */
<div class="children:mb-2">
  <div>每个子元素都有下边距</div>
  <div>每个子元素都有下边距</div>
</div>

6. 升级检查清单

升级前

备份项目代码
记录自定义配置
记录使用的插件
检查是否有动态类名

升级中

升级后

7. 完整迁移示例

7.1 迁移前 (v3)

js 复制代码

// tailwind.config.js
module.exports = {
  content: ["./src/**/*.{html,js}"],
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        brand: '#6366f1',
      },
      fontFamily: {
        sans: ['Inter', 'system-ui'],
      },
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
  ],
}

css 复制代码

/* src/index.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

.btn-primary {
  @apply px-4 py-2 bg-brand text-white rounded hover:bg-brand-dark;
}

7.2 迁移后 (v4)

css 复制代码

/* src/index.css */
@import "tailwindcss";
@plugin "@tailwindcss/typography";

@theme {
  --color-brand: #6366f1;
  --color-brand-dark: #4f46e5;
  --font-sans: 'Inter', system-ui, sans-serif;
}

.btn-primary {
  @apply px-4 py-2 bg-brand text-white rounded hover:bg-brand-dark;
}

js 复制代码

// vite.config.js
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

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

8. 练习

练习 1：迁移配置

将下面的 v3 配置迁移到 v4：

js 复制代码

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6',
        secondary: '#8b5cf6',
      },
      screens: {
        'xs': '480px',
      },
    },
  },
  plugins: [
    require('@tailwindcss/forms'),
  ],
}

参考答案：

css 复制代码

@import "tailwindcss";
@plugin "@tailwindcss/forms";

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #8b5cf6;
  --breakpoint-xs: 480px;
}

9. 总结

对比项	v3	v4
配置位置	`tailwind.config.js`	CSS 文件
主题配置	`theme.extend`	`@theme` 块
插件配置	`plugins` 数组	`@plugin` 指令
自定义类	JavaScript 插件	`@utility` 指令
变体	JavaScript 插件	`@custom-variant`

一句话总结：

Tailwind v4 从 JavaScript 配置转向 CSS 优先，配置更直观，性能更好，但需要按升级指南迁移现有项目。