Tailwind v4 + Vite：5 分钟完整配置模板与目录结构
引言
去年我在一个新项目里配置 Tailwind，折腾了半小时还在改 tailwind.config.js 的 content 路径。那时候我就想：这玩意儿能不能更简单点？
结果今年 Tailwind v4 真的做到了。
你现在只需要三行代码就能跑起来一个完整的 Tailwind 项目——不用 PostCSS 配置、不用 tailwind.config.js、甚至不用手动指定哪些文件要扫描。我第一次看到这个变化的时候，说实话，有点不敢相信。
这篇文章就是帮你省掉那半小时的折腾时间。我会给你一个完整的模板，外加一份我用了半年觉得还挺顺手的目录结构。
1. 为什么选择 Tailwind v4 + Vite？
1.1 v4 真的有那么快吗？
官方说构建速度提升了 10 倍。我测了一下，一个中小型项目从 8 秒变成了不到 1 秒。这个提升主要来自新的 Oxide 引擎——Rust 写的，不用我多说了吧。
但更让我高兴的是配置的简化。以前我新建一个 Tailwind 项目，要改三四个文件：tailwind.config.js、postcss.config.js、vite 配置、还有 CSS 文件里的 @tailwind 指令。现在？改一个文件就够了。
1.2 Vite 的快不是吹的
Vite 的开发服务器启动几乎是瞬间的。热更新（HMR）也特别快，改个 CSS 刷新页面基本感觉不到延迟。这对日常开发体验的提升，说实话，用过就回不去了。
1.3 v3 vs v4：一目了然的对比
别急，先看这个表格：
| 对比项 | Tailwind v3 | Tailwind v4 |
|---|---|---|
| 安装方式 | npm install -D tailwindcss postcss autoprefixer | npm install tailwindcss @tailwindcss/vite |
| 配置文件 | 需要 tailwind.config.js | 不需要，直接在 CSS 里配置 |
| Vite 集成 | 通过 PostCSS 插件 | 官方 Vite 插件 |
| 内容扫描 | 手动配置 content: ['./src/**/*.{html,js}'] | 自动扫描，不用管 |
| 主题配置 | JS 配置对象：theme: { colors: {...} } | CSS 自定义属性：@theme { --color-*: ... } |
看出来了吗？v4 的核心思路就是把配置从 JS 搬到了 CSS 里。这意味着什么？你在写样式的时候就能顺便改配置，不用在两个文件之间跳来跳去了。
2. 5 分钟快速配置模板
准备好了吗？我们开始。
2.1 项目初始化
打开终端，跑这几行：
# 创建一个新的 Vite 项目，用 TypeScript 模板
npm create vite@latest my-project -- --template vanilla-ts
# 进入项目目录
cd my-project
# 安装依赖
npm install这一步大概 30 秒。
2.2 安装 Tailwind v4
# 安装 Tailwind CSS 和官方 Vite 插件
npm install tailwindcss @tailwindcss/vite就这一行。不用 postcss、不用 autoprefixer，因为 v4 已经内置了。
2.3 配置 Vite
打开 vite.config.ts，改成这样：
// vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
// 把 Tailwind 插件加进去就行
plugins: [tailwindcss()],
})三行代码。真的就这么简单。
2.4 创建 CSS 文件
在 src/styles/ 下创建 main.css：
/* src/styles/main.css */
/* 引入 Tailwind — 这一行搞定所有基础样式 */
@import "tailwindcss";
/* 自定义主题配置（可选）*/
@theme {
--color-primary: #3b82f6;
--color-secondary: #10b981;
}这里的 @theme 块是 v4 的新语法。你可以在里面定义自己的颜色、字体、间距等等，用 CSS 变量的形式。比以前写 tailwind.config.js 直观多了。
2.5 引入 CSS
打开 src/main.ts，在最上面加一行：
// src/main.ts
import './styles/main.css'
// 你原本的代码...2.6 测试一下
在 index.html 或某个页面组件里试试：
<div class="bg-primary text-white p-4 rounded-lg">
Tailwind v4 跑起来了！
</div>然后运行：
npm run dev打开浏览器，看到蓝色背景的卡片就说明配置成功了。我掐过时间，真的 5 分钟内能跑起来。
3. 推荐的目录结构
项目跑起来之后，我建议把文件这样组织：
3.1 完整目录结构
my-project/
├── public/
│ └── favicon.ico
├── src/
│ ├── components/
│ │ ├── ui/ # 基础 UI 组件
│ │ │ ├── Button.ts
│ │ │ └── Input.ts
│ │ └── layout/ # 布局组件
│ │ ├── Header.ts
│ │ └── Footer.ts
│ ├── styles/
│ │ ├── main.css # 主入口（引入 Tailwind）
│ │ ├── components.css # 组件相关样式
│ │ └── utilities.css # 自定义工具类
│ ├── utils/
│ │ └── helpers.ts
│ ├── pages/ # 页面文件（如果是多页应用）
│ ├── assets/ # 静态资源
│ │ ├── images/
│ │ └── fonts/
│ ├── main.ts
│ └── vite-env.d.ts
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts3.2 为什么要这样分？
components/ui/ 放基础组件——按钮、输入框、弹窗这些。它们可复用性强，不依赖具体业务逻辑。
components/layout/ 放布局组件——Header、Footer、Sidebar。这些组件负责页面骨架，和 ui 组件的定位不太一样。
styles/ 单独放 CSS。Tailwind v4 之后我更喜欢把样式集中管理了，因为配置都在 CSS 里，放一起改起来方便。
utils/ 放工具函数。格式化日期、处理字符串之类的纯函数。
3.3 CSS 文件怎么组织
/* src/styles/main.css — 入口文件 */
/* 引入 Tailwind */
@import "tailwindcss";
/* 引入其他样式文件 */
@import "./components.css";
@import "./utilities.css";
/* 全局基础样式 */
@layer base {
body {
@apply bg-gray-50 text-gray-900;
}
/* 超链接默认样式 */
a {
@apply text-primary hover:underline;
}
}@layer base 是 Tailwind 的分层机制，用来定义最底层的样式。这比直接写 body { ... } 更好的地方在于：Tailwind 会帮你处理好优先级问题。
4. v3 迁移清单
如果你手头有 v3 项目想升级，照着这个清单来就行。我前阵子升级了好几个项目，踩过的坑都给你标出来了。
4.1 配置文件迁移
- 删除
tailwind.config.js（如果只有 Tailwind 配置的话） - 删除
postcss.config.js（如果只用于 Tailwind 的话） - 在 CSS 文件里加一行
@import "tailwindcss" - 更新
vite.config.ts，换成@tailwindcss/vite插件
4.2 依赖更新
# 卸载旧依赖
npm uninstall postcss autoprefixer tailwindcss
# 安装新依赖
npm install tailwindcss @tailwindcss/vite- 运行卸载命令
- 运行安装命令
- 检查
package.json确认版本号
4.3 样式调整
- 把
@tailwind base; @tailwind components; @tailwind utilities;替换成@import "tailwindcss"; - 把
tailwind.config.js里的主题配置迁移到 CSS 的@theme块 - 确认自定义的工具类还能正常工作
主题配置迁移示例：
/* v3 的 tailwind.config.js */
module.exports = {
theme: {
colors: {
primary: '#3b82f6',
}
}
}
/* v4 的 main.css */
@theme {
--color-primary: #3b82f6;
}4.4 测试验证
-
npm run dev检查开发环境是否正常 -
npm run build检查生产构建是否成功 - 打开页面确认样式没丢
- 改个 CSS 文件，看看热更新是否工作
5. 常见问题与解决方案
升级和配置过程中，我遇到得最多的问题就这几个。
5.1 样式不生效
你写了 class="bg-primary"，页面上一片白。怎么回事？
排查步骤：
- 打开浏览器开发者工具，看看 CSS 文件有没有加载成功
- 确认
main.ts里是不是真的引入了 CSS 文件 - 检查
vite.config.ts里插件是不是配置对了
我碰到过一次是因为忘记在 main.ts 里 import './styles/main.css'。很低级的错误，但确实容易漏。
5.2 热更新不工作
改了 CSS，页面纹丝不动。
排查步骤：
- 确认 Vite 版本 >= 5.0（老版本有兼容问题）
- 重启开发服务器试试
- 清除浏览器缓存，或者开个无痕窗口
如果还不行，检查控制台有没有报错。有时候是其他插件冲突导致的。
5.3 构建后 CSS 体积太大
生产环境构建出来，CSS 文件动辄几百 KB。
排查步骤：
- 确认你用的是 v4 的新版本，旧版本的 tree-shaking 不够干净
- 检查有没有引入了整个图标库或其他大型依赖
- 用
@layer把样式分层，Tailwind 会更好地处理优先级和去重
说实话，大部分情况下 v4 的输出已经很精简了。如果还是太大，大概率是你自己在 CSS 里写了太多东西。
总结
说了这么多，核心就这几件事：
- 安装：
npm install tailwindcss @tailwindcss/vite - 配置 Vite：加一个
tailwindcss()插件 - 写 CSS：
@import "tailwindcss"+@theme配置主题 - 跑起来：
npm run dev
v4 相比 v3 最大的变化就是把配置从 JS 搬到了 CSS 里。一开始可能会有点不习惯，但用了一段时间后我发现这样更直观——改样式的时候顺手就把配置改了，不用在文件之间跳来跳去。
如果你是从 v3 迁移过来的，记得把 tailwind.config.js 里的主题配置翻译成 CSS 的 @theme 语法。虽然要花点时间，但换来的是更快的构建速度和更简洁的项目结构，这笔账怎么算都划算。
配置 Tailwind v4 + Vite 项目
5 分钟完成 Tailwind CSS v4 与 Vite 的集成配置
⏱️ 预计耗时: 5 分钟
- 1
步骤1: 创建项目并安装依赖
运行以下命令：
```bash
npm create vite@latest my-project -- --template vanilla-ts
cd my-project
npm install
npm install tailwindcss @tailwindcss/vite
```
无需安装 postcss 和 autoprefixer，v4 已内置。 - 2
步骤2: 配置 Vite 插件
修改 `vite.config.ts`：
```typescript
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins: [tailwindcss()],
})
```
只需三行代码，无需其他配置文件。 - 3
步骤3: 创建 CSS 入口文件
创建 `src/styles/main.css`：
```css
@import "tailwindcss";
@theme {
--color-primary: #3b82f6;
}
```
`@theme` 块用于自定义主题，用 CSS 变量语法。 - 4
步骤4: 引入 CSS 并验证
在 `src/main.ts` 顶部添加：
```typescript
import './styles/main.css'
```
运行 `npm run dev`，在页面中使用 Tailwind 类名验证是否生效。 - 5
步骤5: v3 迁移（可选）
从 v3 迁移需要：
• 删除 `tailwind.config.js` 和 `postcss.config.js`
• 将 `@tailwind` 指令替换为 `@import "tailwindcss"`
• 将 JS 主题配置迁移到 `@theme` CSS 块
• 更新依赖：卸载旧包，安装 v4 版本
常见问题
Tailwind v4 与 v3 的核心区别是什么？
v4 还需要 PostCSS 吗？
如何迁移 v3 的主题配置？
```css
@theme {
--color-primary: #3b82f6;
--color-secondary: #10b981;
}
```
颜色、字体、间距等配置均支持此语法。
样式不生效怎么排查？
v4 支持哪些 Vite 版本？
8 分钟阅读 · 发布于: 2026年3月25日 · 修改于: 2026年3月25日
评论
使用 GitHub 账号登录后即可评论