Tailwind CSS v4 迁移指南：从 v3 升级你需要知道的一切
Tailwind CSS v4 Migration Guide Everything You Need to Know
| iDev Team | 2026-08-06T07:36:00
Tailwind CSS v4 带来了全新的引擎、CSS-first 配置和自动内容检测。本文整理了从 v3 迁移到 v4 的完整步骤和注意事项。
Tailwind CSS v4 features a new engine, CSS-first configuration, and automatic content detection. This guide covers the complete migration steps from v3 to v4.
Tailwind v4 的重大变化 Tailwind CSS v4 是一次革命性的升级，核心引擎用 Rust 重写（Oxide），构建速度提升了 10 倍。以下是最重要的变化： 1. CSS-first 配置 不再需要 tailwind.config.js，所有配置直接写在 CSS 文件中： @import "tailwindcss"; @theme { --color-primary: #007AFF; --font-sans: "Inter", sans-serif; --breakpoint-lg: 1024px; } 2. 自动内容检测 v4 自动扫描项目中的所有文件，不再需要手动配置 content 数组。它使用文件系统 watcher 实时检测变化。 3. 原生 CSS 嵌套 利用浏览器原生的 CSS 嵌套支持，不再依赖 PostCSS 嵌套插件。 迁移步骤 升级依赖：npm install tailwindcss@latest 使用官方迁移工具：npx @tailwindcss/upgrade 将 tailwind.config.js 中的自定义主题迁移到 CSS 的 @theme 指令 移除不再需要的 PostCSS 插件 更新被重命名的 Utility 类 被重命名的类 bg-opacity-* → bg-*/opacity shadow-sm → shadow-xs，shadow → shadow-sm ring → ring-3 blur → blur-sm 迁移注意事项 如果你使用了自定义插件，需要检查兼容性。v4 的插件 API 有较大变化，部分社区插件可能需要等待更新。建议在新分支上测试迁移，确认无问题后再合并。
Major Changes in Tailwind v4 Tailwind CSS v4 is a revolutionary upgrade with its core engine rewritten in Rust (Oxide), delivering 10x faster build times. Here are the most important changes: 1. CSS-First Configuration No more tailwind.config.js — all configuration is written directly in CSS: @import "tailwindcss"; @theme { --color-primary: #007AFF; --font-sans: "Inter", sans-serif; --breakpoint-lg: 1024px; } 2. Automatic Content Detection v4 automatically scans all project files — no more manual content array configuration. It uses a filesystem watcher for real-time change detection. 3. Native CSS Nesting Leverages browser-native CSS nesting support, eliminating the need for PostCSS nesting plugins. Migration Steps Upgrade dependencies: npm install tailwindcss@latest Use the official migration tool: npx @tailwindcss/upgrade Migrate custom themes from tailwind.config.js to the CSS @theme directive Remove unnecessary PostCSS plugins Update renamed utility classes Renamed Classes bg-opacity-* → bg-*/opacity shadow-sm → shadow-xs, shadow → shadow-sm ring → ring-3 blur → blur-sm Migration Considerations If you use custom plugins, check compatibility. v4's plugin API has significant changes, and some community plugins may need updates. Test the migration on a separate branch and confirm everything works before merging.