前言
Tailwind CSS v4 于 2025年1月22日正式发布，带来了革命性的变化。本文基于实际迁移 Next.js 15 + shadcn/ui 项目的经验，提供完整的迁移指南。
主要变化概览
🚀 核心改进
- 性能提升: 构建速度提升 5 倍，增量构建提升 100+ 倍
- CSS-first 配置: 从 JavaScript 配置改为 CSS 中配置
- 现代 CSS 特性: 使用 cascade layers、@property 等新特性
- 更好的开发体验: 微秒级的增量构建
⚠️ 兼容性要求
- 浏览器支持: Safari 16.4+, Chrome 111+, Firefox 128+
- Next.js: 完全兼容，但需要手动配置
- shadcn/ui: 官方支持 v4
迁移步骤
1. 升级 Tailwind CSS
# 升级到 v4
npm install tailwindcss@latest
# 安装必要的 PostCSS 插件
npm install @tailwindcss/postcss
2. 更新 PostCSS 配置
将 postcss.config.mjs 更新为：
/** @type {import('postcss-load-config').Config} */
const config = {
plugins: ["@tailwindcss/postcss"],
};
export default config;
3. 删除旧配置文件
# 删除 Tailwind v3 配置文件
rm tailwind.config.ts
# 或
rm tailwind.config.js
4. 迁移到 CSS-first 配置
4.1 更新 globals.css
将原来的：
@tailwind base;
@tailwind components;
@tailwind utilities;
改为：
@import "tailwindcss";
@plugin "tailwindcss-animate";
4.2 迁移主题配置
将原 tailwind.config.ts 中的配置迁移到 CSS 中：
@theme {
/* 字体配置 */
--font-sans: -apple-system, BlinkMacSystemFont, 'Noto Sans SC', system-ui, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Helvetica Neue', Helvetica, Arial, sans-serif;
--font-mono: 'SF Mono', Monaco, 'Inconsolata', 'Roboto Mono', 'Source Code Pro', Menlo, Consolas, 'DejaVu Sans Mono', monospace;
/* 容器配置 - 替代原 container 配置 */
--container-center: true;
--container-padding: 2rem;
--container-max-width-2xl: 1400px;
}
@theme inline {
/* shadcn/ui 颜色变量映射 */
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-card: var(--card);
--color-card-foreground: var(--card-foreground);
--color-popover: var(--popover);
--color-popover-foreground: var(--popover-foreground);
--color-primary: var(--primary);
--color-primary-foreground: var(--primary-foreground);
--color-secondary: var(--secondary);
--color-secondary-foreground: var(--secondary-foreground);
--color-muted: var(--muted);
--color-muted-foreground: var(--muted-foreground);
--color-accent: var(--accent);
--color-accent-foreground: var(--accent-foreground);
--color-destructive: var(--destructive);
--color-destructive-foreground: var(--destructive-foreground);
--color-border: var(--border);
--color-input: var(--input);
--color-ring: var(--ring);
/* 圆角配置 */
--radius-sm: calc(var(--radius) - 4px);
--radius-md: calc(var(--radius) - 2px);
--radius-lg: var(--radius);
--radius-xl: calc(var(--radius) + 4px);
}
4.3 保留 shadcn/ui 颜色变量
保持原有的 CSS 变量定义：
:root {
--background: oklch(0.9766 0.0017 67.8025);
--foreground: oklch(0 0 0);
--card: oklch(1.0000 0 0);
/* ... 其他颜色变量 */
--radius: 0.5rem;
}
.dark {
--background: oklch(0.2178 0 0);
--foreground: oklch(0.9766 0.0017 67.8025);
/* ... 暗色模式变量 */
}
4.4 更新自定义变体
如果使用暗色模式，添加自定义变体：
@custom-variant dark (&:is(.dark *));
5. 修复常见问题
5.1 边框颜色问题
如果遇到 border-border 类不被识别的错误，更新为：
@layer base {
* {
@apply outline-ring/50;
border-color: hsl(var(--border));
}
body {
@apply bg-background text-foreground;
}
}
5.2 动画插件配置
确保 tailwindcss-animate 正确加载：
@plugin "tailwindcss-animate";
6. 测试和验证
# 测试构建
npm run build
# 启动开发服务器
npm run dev
完整示例
package.json 依赖
{
"devDependencies": {
"tailwindcss": "^4.1.12",
"tailwindcss-animate": "^1.0.7",
"@tailwindcss/postcss": "^4.1.12",
"autoprefixer": "^10.4.20",
"postcss": "^8"
}
}
完整的 globals.css
@import "tailwindcss";
@plugin "tailwindcss-animate";
@custom-variant dark (&:is(.dark *));
@theme {
--font-sans: -apple-system, BlinkMacSystemFont, 'Noto Sans SC', system-ui, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Helvetica Neue', Helvetica, Arial, sans-serif;
--font-mono: 'SF Mono', Monaco, 'Inconsolata', 'Roboto Mono', 'Source Code Pro', Menlo, Consolas, 'DejaVu Sans Mono', monospace;
}
@theme inline {
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-sidebar-ring: var(--sidebar-ring);
--color-border: var(--border);
--color-input: var(--input);
--color-ring: var(--ring);
--radius-sm: calc(var(--radius) - 4px);
--radius-md: calc(var(--radius) - 2px);
--radius-lg: var(--radius);
--radius-xl: calc(var(--radius) + 4px);
}
:root {
--radius: 0.5rem;
--background: oklch(0.9766 0.0017 67.8025);
--foreground: oklch(0 0 0);
--card: oklch(1.0000 0 0);
--card-foreground: oklch(0 0 0);
--popover: oklch(1.0000 0 0);
--popover-foreground: oklch(0 0 0);
--primary: oklch(0.6606 0.0950 53.8176);
--primary-foreground: oklch(1.0000 0 0);
--secondary: oklch(0.9702 0 0);
--secondary-foreground: oklch(0 0 0);
--muted: oklch(0.9219 0 0);
--muted-foreground: oklch(0.5555 0 0);
--accent: oklch(0.6606 0.0950 53.8176);
--accent-foreground: oklch(0 0 0);
--destructive: oklch(0.5845 0.1216 34.8390);
--destructive-foreground: oklch(1.0000 0 0);
--border: oklch(0.9219 0 0);
--input: oklch(0.9219 0 0);
--ring: oklch(0.6606 0.0950 53.8176);
}
.dark {
--background: oklch(0.2178 0 0);
--foreground: oklch(0.9766 0.0017 67.8025);
--card: oklch(0.2686 0 0);
--card-foreground: oklch(0.9766 0.0017 67.8025);
--popover: oklch(0.2686 0 0);
--popover-foreground: oklch(0.9766 0.0017 67.8025);
--primary: oklch(0.6606 0.0950 53.8176);
--primary-foreground: oklch(0 0 0);
--secondary: oklch(0.3715 0 0);
--secondary-foreground: oklch(0.9766 0.0017 67.8025);
--muted: oklch(0.3715 0 0);
--muted-foreground: oklch(0.7155 0 0);
--accent: oklch(0.6606 0.0950 53.8176);
--accent-foreground: oklch(0 0 0);
--destructive: oklch(0.5845 0.1216 34.8390);
--destructive-foreground: oklch(0 0 0);
--border: oklch(0.3715 0 0);
--input: oklch(0.2686 0 0);
--ring: oklch(0.6606 0.0950 53.8176);
}
@layer base {
* {
@apply outline-ring/50;
border-color: hsl(var(--border));
}
body {
@apply bg-background text-foreground;
}
}
常见问题
Q: 样式没有加载怎么办？
A: 检查 PostCSS 配置是否正确，确保使用了 @tailwindcss/postcss 插件。
Q: shadcn/ui 组件样式异常？
A: 确保在 @theme inline 中正确映射了所有颜色变量。
Q: 动画效果失效？
A: 确保正确加载了 @plugin "tailwindcss-animate"。
Q: 构建失败？
A: 检查是否删除了旧的 tailwind.config.js 文件，避免配置冲突。
性能对比
迁移前后的构建性能对比：
| 指标 | v3 | v4 | 提升 |
|---|---|---|---|
| 全量构建 | ~15s | ~3s | 5x |
| 增量构建 | ~2s | ~20ms | 100x |
| 开发启动 | ~3s | ~1s | 3x |
总结
Tailwind CSS v4 的迁移主要工作量在于：
- 配置方式的改变（JS → CSS）
- PostCSS 插件的更新
- 变量映射的调整
虽然需要一些手动工作，但带来的性能提升和开发体验改善是显著的。对于现代浏览器环境，强烈推荐升级到 v4。
本文基于实际项目迁移经验编写，如有问题可参考 Tailwind CSS v4 官方文档
评论区