当前位置：首页 > ops >正文

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

ops 2025/9/3 13:56:35

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 配置抄过来就会报错