Vite + React + Tailwind v4 正确配置指南(避免掉进 v3 的老坑)

Vite + React + Tailwind v4 正确配置指南(避免掉进 v3 的老坑)

很多同学在用 Vite + React 搭建项目时会选择 Tailwind CSS。
但是 Tailwind v4 与 v3 的配置差别很大，如果照着 v3 的教程去做，经常会报错或者样式不生效。
本文通过一个实战案例，带你理清 v3 和 v4 的区别，避免踩坑。

1. 环境准备

在开始之前，先准备一个 Vite + React 项目：

npm create vite@latest my-vite-app
cd my-vite-app
npm install

1.1 安装 Tailwind v4

运行以下命令安装最新的 Tailwind（注意当前最新版本号 4.x.x）：

npm install -D tailwindcss postcss autoprefixer @tailwindcss/postcss

这里要特别注意：

• 在 v4 中，Tailwind 的 PostCSS 插件已经拆分成单独的包 @tailwindcss/postcss。
• 如果你继续用 tailwindcss: {} 作为 PostCSS 插件，就会报错。

1.1.1 创建配置文件

在项目根目录新建 postcss.config.js：

export default {
  plugins: {
    '@tailwindcss/postcss': {},
    autoprefixer: {},
  },
}

在项目根目录新建 tailwind.config.js（虽然 v4 可以零配置，但建议显式指定 content 扫描范围）：

/** @type {import('tailwindcss').Config} */
export default {
  content: ["./index.html", "./src/**/*.{js,jsx,ts,tsx}"],
  theme: {
    extend: {},
  },
  plugins: [],
}

1.1.1.1 编辑入口样式

在 src/index.css 中，只保留 一行：

@import "tailwindcss";

⚠️ 注意：

• v3 写法是

  @tailwind base;
  @tailwind components;
  @tailwind utilities;
  

• v4 写法是

  @import "tailwindcss";
  

很多人就是在这里混淆了版本，结果导致样式不生效。
v4的配置如下图：

1.2 确认入口文件引入 CSS

在 src/main.jsx 中引入 index.css：

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.jsx'
import './index.css'   // 必须引入 Tailwind 样式

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
)

1.2.1 测试 Tailwind 是否生效

在 src/App.jsx 中写一个简单的例子：

export default function App() {
  return (
    <div className="min-h-screen flex items-center justify-center bg-gradient-to-r from-pink-300 to-blue-300">
      <h1 className="text-5xl font-bold text-white">Hello Tailwind v4 🎉</h1>
    </div>
  )
}

运行项目：

npm run dev

浏览器中应能看到一个渐变背景，白色大号字体。
如下图：

2. 常见错误与对比

2.1 v3 配置方式

在 v3 中，你通常会这样写：

• index.css

  @tailwind base;
  @tailwind components;
  @tailwind utilities;
  

• postcss.config.js

  export default {
    plugins: {
      tailwindcss: {},
      autoprefixer: {},
    },
  }
  

2.2 v4 配置方式

而在 v4 中，需要改成：

• index.css

  @import "tailwindcss";
  

• postcss.config.js

  export default {
    plugins: {
      '@tailwindcss/postcss': {},
      autoprefixer: {},
    },
  }
  

2.2.1 总结对比

3. 结语

Tailwind v4 做了很多简化：

• 入口 CSS 只要一句 @import "tailwindcss";
• PostCSS 插件要用 @tailwindcss/postcss

但是因为很多教程还停留在 v3 版本，很多人（包括我自己 😅）会把配置搞混。
如果你发现 样式不生效 或者 报错找不到插件，十有八九就是 v3 和 v4 配置混淆了。

希望这篇文章能帮你少踩坑，更快地用上 Tailwind v4 🚀。