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 总结对比

对比项	Tailwind v3	Tailwind v4
引入方式	@tailwind base/components/utilities	@import "tailwindcss";
PostCSS 插件	tailwindcss: {}	@tailwindcss/postcss: {}
是否需要配置	必须写 tailwind.config.js	可零配置，但推荐写 content
新手常见报错	无法找到指令 / 样式不生效	直接把 v3 配置抄过来就会报错

---

3. 结语

Tailwind v4 做了很多简化：

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

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

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