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：一目了然的对比

别急，先看这个表格：

看出来了吗？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()],
})

三行代码。真的就这么简单。

Vultr - 高性能 NVMe 云服务器，32 个全球节点可选，支持一键部署 Docker

查看定价 →推广

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.ts

3.2 为什么要这样分？

components/ui/ 放基础组件——按钮、输入框、弹窗这些。它们可复用性强，不依赖具体业务逻辑。

components/layout/ 放布局组件——Header、Footer、Sidebar。这些组件负责页面骨架，和 ui 组件的定位不太一样。

styles/ 单独放 CSS。Tailwind v4 之后我更喜欢把样式集中管理了，因为配置都在 CSS 里，放一起改起来方便。

utils/ 放工具函数。格式化日期、处理字符串之类的纯函数。

Railway - 现代化的部署平台，告别繁琐运维，让代码分钟级上线

立即开始 →推广

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"，页面上一片白。怎么回事？

排查步骤：

1. 打开浏览器开发者工具，看看 CSS 文件有没有加载成功
2. 确认 main.ts 里是不是真的引入了 CSS 文件
3. 检查 vite.config.ts 里插件是不是配置对了

我碰到过一次是因为忘记在 main.ts 里 import './styles/main.css'。很低级的错误，但确实容易漏。

5.2 热更新不工作

改了 CSS，页面纹丝不动。

阿里云 - 开发者上云首选，轻量服务器专享 8.5 折优惠，助力项目快速上线

领取 8.5 折优惠 →推广

排查步骤：

1. 确认 Vite 版本 >= 5.0（老版本有兼容问题）
2. 重启开发服务器试试
3. 清除浏览器缓存，或者开个无痕窗口

如果还不行，检查控制台有没有报错。有时候是其他插件冲突导致的。

5.3 构建后 CSS 体积太大

生产环境构建出来，CSS 文件动辄几百 KB。

排查步骤：

1. 确认你用的是 v4 的新版本，旧版本的 tree-shaking 不够干净
2. 检查有没有引入了整个图标库或其他大型依赖
3. 用 @layer 把样式分层，Tailwind 会更好地处理优先级和去重

说实话，大部分情况下 v4 的输出已经很精简了。如果还是太大，大概率是你自己在 CSS 里写了太多东西。

总结

说了这么多，核心就这几件事：

1. 安装：npm install tailwindcss @tailwindcss/vite
2. 配置 Vite：加一个 tailwindcss() 插件
3. 写 CSS：@import "tailwindcss" + @theme 配置主题
4. 跑起来：npm run dev

v4 相比 v3 最大的变化就是把配置从 JS 搬到了 CSS 里。一开始可能会有点不习惯，但用了一段时间后我发现这样更直观——改样式的时候顺手就把配置改了，不用在文件之间跳来跳去。

如果你是从 v3 迁移过来的，记得把 tailwind.config.js 里的主题配置翻译成 CSS 的 @theme 语法。虽然要花点时间，但换来的是更快的构建速度和更简洁的项目结构，这笔账怎么算都划算。

8 分钟阅读 · 发布于: 2026年3月25日 · 修改于: 2026年3月25日

Easton

技术开发