跳到主要内容

安装与配置

本章介绍如何在项目中安装和配置 Tailwind CSS v4.0。v4.0 带来了全新的安装体验，配置更简单，性能更强大。

v4.0 安装方式的重大变化​

Tailwind CSS v4.0 对安装和配置进行了重大简化：

  • 一行 CSS 导入：不再需要多个 @tailwind 指令，只需 @import "tailwindcss"
  • 零配置启动：无需配置 content 路径，自动检测模板文件
  • CSS-first 配置：不再需要 JavaScript 配置文件，直接在 CSS 中配置
  • 更少的依赖：内置 import 支持，无需额外插件

使用 Vite 安装（推荐）​

Vite 是现代前端项目的首选构建工具，与 Tailwind CSS v4.0 配合使用体验最佳。

步骤一：创建项目​

如果你还没有 Vite 项目，可以先创建一个：

npm create vite@latest my-project
cd my-project
npm install

步骤二：安装 Tailwind CSS​

安装 Tailwind CSS 及其 Vite 插件：

npm install tailwindcss @tailwindcss/vite

步骤三：配置 Vite 插件​

在 vite.config.js 中添加 Tailwind CSS 插件：

import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    tailwindcss(),
  ],
})

步骤四：导入 Tailwind CSS​

在你的主 CSS 文件中添加一行导入：

@import "tailwindcss";

就这么简单！不再需要三个 @tailwind 指令，不再需要配置文件。

步骤五：开始使用​

现在你可以在 HTML 中使用 Tailwind 的工具类了：

<h1 class="text-3xl font-bold text-blue-500">
  Hello Tailwind CSS v4.0!
</h1>

使用 PostCSS 安装​

如果你使用的是 Webpack、Rollup 等其他构建工具，可以通过 PostCSS 集成 Tailwind CSS。

安装依赖​

npm install tailwindcss @tailwindcss/postcss

配置 PostCSS​

创建或更新 postcss.config.js：

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

导入 Tailwind CSS​

在你的主 CSS 文件中添加：

@import "tailwindcss";

v4.0 不再需要三个 @tailwind 指令，只需一行导入即可。

使用 Tailwind CLI​

对于简单的项目或快速原型，可以直接使用 Tailwind CLI。

安装​

npm install -D tailwindcss

创建输入文件​

创建 input.css 文件：

@import "tailwindcss";

构建 CSS​

npx tailwindcss -i ./src/input.css -o ./dist/output.css --watch

这会监听文件变化并自动重新构建。

v4.0 的 CLI 构建极快：

  • 完整构建：比 v3 快 3-5 倍
  • 增量构建：比 v3 快 8-100 倍
  • 无新 CSS 时增量构建：微秒级完成

使用 Play CDN（仅用于开发测试）​

Play CDN 适合快速测试和学习，不建议在生产环境使用。

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://cdn.tailwindcss.com"></script>
</head>
<body>
  <h1 class="text-3xl font-bold text-blue-500">
    Hello Tailwind CSS!
  </h1>
</body>
</html>
注意

Play CDN 会在浏览器中运行 Tailwind，性能较差，仅适合开发测试使用。v4.0 的 CDN 目前仍在开发中。

框架集成指南​

Next.js​

Next.js 推荐使用 Vite 方式或 PostCSS 方式集成：

使用 Vite（App Router 推荐）：

npm install tailwindcss @tailwindcss/vite

配置 vite.config.ts：

import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [tailwindcss()],
})

使用 PostCSS：

npm install tailwindcss @tailwindcss/postcss

配置 postcss.config.js：

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

在 app/globals.css 中导入：

@import "tailwindcss";

React (Create React App)​

npm install tailwindcss @tailwindcss/postcss

配置 postcss.config.js：

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

在 src/index.css 中添加：

@import "tailwindcss";

Vue​

npm install tailwindcss @tailwindcss/postcss

配置 postcss.config.js：

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

在 src/assets/main.css 中添加：

@import "tailwindcss";

然后在 main.js 中导入：

import './assets/main.css'

v4.0 配置文件详解​

CSS-first 配置​

v4.0 最大的变化是从 JavaScript 配置文件迁移到 CSS 中配置。不再需要 tailwind.config.js，直接在 CSS 文件中配置：

@import "tailwindcss";

@theme {
  /* 自定义字体 */
  --font-display: "Satoshi", sans-serif;
  
  /* 自定义颜色（使用 OKLCH 获得更鲜艳的颜色） */
  --color-brand-500: oklch(0.7 0.15 165);
  
  /* 自定义断点 */
  --breakpoint-3xl: 1920px;
  
  /* 自定义动画曲线 */
  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
}

CSS 变量自动暴露​

v4.0 会自动将所有设计令牌暴露为 CSS 变量，你可以在任何地方使用：

.custom-element {
  font-family: var(--font-display);
  background-color: var(--color-brand-500);
}

指定内容源（可选）​

v4.0 默认自动检测内容文件，但如果需要指定额外的源：

@import "tailwindcss";

@source "../node_modules/@my-company/ui-lib";

v3 到 v4 配置迁移​

如果你有 v3 的 tailwind.config.js：

// v3 配置
export default {
  content: ['./src/**/*.{html,js}'],
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6',
      },
    },
  },
}

迁移到 v4：

@import "tailwindcss";

@source "./src/**/*.{html,js}";

@theme {
  --color-brand: #3b82f6;
}

自动内容检测​

v4.0 最大的改进之一是自动内容检测，不再需要手动配置 content 路径。

自动检测机制​

Tailwind v4.0 会自动：

  1. 扫描项目中的模板文件
  2. 忽略 .gitignore 中列出的目录
  3. 排除二进制文件（图片、视频、zip 等）

默认忽略的路径：

/node_modules/
coverage/
.next/
/build/
dist/

手动指定内容源​

如果需要包含被默认排除的路径，使用 @source 指令：

@import "tailwindcss";

/* 添加额外的内容源 */
@source "../node_modules/@my-company/ui-lib";

/* 排除特定路径 */
@source inline("node_modules/some-lib/**");

开发工具配置​

VS Code 插件​

安装 Tailwind CSS IntelliSense 插件，获得以下功能：

  • 类名自动补全
  • 悬停预览 CSS
  • 语法高亮
  • 错误提示
  • v4.0 语法支持

配置建议​

在 .vscode/settings.json 中添加：

{
  "tailwindCSS.includeLanguages": {
    "vue": "html",
    "vue-html": "html"
  },
  "editor.quickSuggestions": {
    "strings": "on"
  },
  "files.associations": {
    "*.css": "tailwindcss"
  }
}

验证安装​

创建一个测试文件验证 Tailwind 是否正常工作：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Tailwind CSS v4.0 测试</title>
  <link href="/dist/output.css" rel="stylesheet">
</head>
<body class="bg-gray-100 min-h-screen flex items-center justify-center">
  <div class="bg-white p-8 rounded-lg shadow-md">
    <h1 class="text-2xl font-bold text-gray-800 mb-4">
      Tailwind CSS v4.0 安装成功！
    </h1>
    <p class="text-gray-600">
      如果你能看到这个卡片的样式，说明 Tailwind CSS 已经正常工作。
    </p>
    <button class="mt-4 bg-blue-500 hover:bg-blue-600 text-white px-4 py-2 rounded transition-colors">
      测试按钮
    </button>
  </div>
</body>
</html>

从 v3 升级到 v4​

使用自动升级工具​

Tailwind 提供了自动升级工具：

npx @tailwindcss/upgrade@next

这个工具会：

  • 更新依赖
  • 迁移配置到 CSS
  • 更新类名变化
  • 移除不再需要的插件

主要迁移点​

v3v4
@tailwind base; @tailwind components; @tailwind utilities;@import "tailwindcss";
tailwind.config.jsCSS 中的 @theme
@tailwindcss/container-queries 插件内置支持
bg-opacity-50bg-blue-500/50
bg-gradient-to-rbg-linear-to-r

小结​

本章介绍了 Tailwind CSS v4.0 的安装方式：

  • Vite 插件：现代项目的推荐方式，性能最佳
  • PostCSS：适用于 Webpack、Rollup 等构建工具
  • CLI：适合简单项目或快速原型
  • Play CDN：仅用于学习和测试

v4.0 的重大变化：

  • 一行 CSS 导入，无需多个指令
  • 零配置启动，自动检测内容
  • CSS-first 配置，无需 JavaScript 文件
  • 性能大幅提升，增量构建微秒级完成

选择适合你项目的安装方式，下一章我们将学习 Tailwind CSS 的核心理念。