最推荐路径是直接使用@tailwindcss/vite插件,不配PostCSS、不写postcss.config.js、不运行npx tailwindcss init;它仅适用于纯Vite项目(如create vite创建的模板),禁用于Next.js等非纯Vite环境,且必须版本一致、插件仅置于vite.config.ts的plugins数组中,CSS入口首行须为@import "tailwindcss";。

直接用 @tailwindcss/vite 插件,不配 PostCSS、不写 postcss.config.js、不手动运行 npx tailwindcss init —— 这是当前(2026年)Vite 项目里最轻量、热更新最稳的路径。选错集成方式,开发时看着有样式,构建后全丢。
确认项目类型再装插件
不是所有“Vite 项目”都能用 @tailwindcss/vite。它只认纯 Vite 构建链:
- ✅ 能用:
npm create vite@latest创建的 React/Vue/Svelte 模板、Rolldown-Vite 实验项目 - ❌ 不能用:Next.js、Nuxt、CRA、Taro、uni-app(除非用
@uni-helper/vite-plugin-uni-tailwind) - ⚠️ 混搭高危:已有
postcss.config.js或手动在vite.config.ts里写了css.postcss.plugins的项目,加了@tailwindcss/vite会触发双重扫描,热更新失效或 class 漏扫
安装与 vite.config.ts 配置要点
必须同时安装两个包,且版本号完全一致(比如都是 v4.0.2):
npm install -D tailwindcss@4.0.2 @tailwindcss/vite@4.0.2
在 vite.config.ts 中只做一件事:把插件加进 plugins 数组:
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
<p>export default defineConfig({
plugins: [react(), tailwindcss()], // ✅ 只放这里
})</p>
绝不能出现以下写法:
-
css.postcss.plugins: [tailwindcss()]—— 插件不接管这个字段 - 在
plugins外调用tailwindcss()—— 无效 - 同时存在
@tailwindcss/vite和@tailwindcss/postcss—— 冲突
CSS 入口文件必须以 @import "tailwindcss"; 开头
这是最容易静默失败的点:Tailwind 的 @import 必须是 CSS 文件里的第一行,前面不能有任何内容(包括注释、空行、其他 @import)。
正确示例(src/style.css):
@import "tailwindcss"; @import "./base.css";
错误示例:
-
/* reset */\n@import "tailwindcss";—— 注释导致解析跳过 -
@import "./vars.css";\n@import "tailwindcss";—— 顺序错,tailwindcss不被识别为入口 - 在
.module.css或 Vue 的里写 —— 全局类(如bg-red-500)不会进入作用域,必须放在非 scoped 全局 CSS 中
动态 class 和 content 扫描范围要小心
@tailwindcss/vite 默认只扫描 .vue 和 .tsx 文件中的静态 class 字符串。如果你用了这些写法,样式大概率不生效:
- Vue 中:
:class="'bg-' + color"—— 插件无法分析字符串拼接 - React 中用
.jsx(非 TSX)—— 默认不扫描,需手动加tailwind.config.js并设content: ["./src/**/*.{js,jsx,ts,tsx}"] - 模板字符串里拼 class:
className={`p-4 ${isActive ? 'bg-blue-500' : ''}`}—— 静态分析失败,bg-blue-500可能被 purge
真正难排查的是:开发时热更新看起来正常,但 npm run build 后部分 class 消失 —— 根源几乎都在 content 扫描没覆盖到,或者用了插件不支持的动态写法。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











