TailwindCSS的使用，看这一篇就够了！

Category（分类）: CSS
Status: 未知

本文示例以 Vite + Vue 为主，尽量保留 Tailwind CSS v3 的经典用法，并补充 Tailwind CSS v4 的安装方式。

版本说明： tailwind.config.js、content 配置、@tailwind base/components/utilities、theme() 和 tailwindcss/nesting 主要属于 Tailwind CSS v3。新项目使用 Tailwind CSS v4 时，请按照文中的 v4 小节配置，不要混用两套配置。

一、安装 Tailwind CSS

1.1 Tailwind CSS v3：Vite + Vue

以下方法是 Vite + Vue 模式下的安装方法，其他脚手架与框架的使用思路类似，但配置入口可能不同。

创建项目

pnpm create vite app --template vue
cd app

# 也可以使用：
# yarn create vite app --template vue
# npm create vite@latest app -- --template vue

安装必要依赖

Vite 支持通过 PostCSS 处理 CSS。Tailwind CSS v3 本身是一个 PostCSS 插件，因此需要安装 Tailwind CSS、PostCSS 和 Autoprefixer：

pnpm add -D tailwindcss@3 postcss autoprefixer

# 也可以使用：
# yarn add -D tailwindcss@3 postcss autoprefixer
# npm install -D tailwindcss@3 postcss autoprefixer

这里显式安装 tailwindcss@3，是为了避免安装到 Tailwind CSS v4 后继续使用 v3 的配置和命令。

创建 Tailwind CSS 配置文件

使用初始化命令可以同时创建 tailwind.config.js 和 postcss.config.js：

pnpm exec tailwindcss init -p

如果项目使用的是 npm，也可以执行：

npx tailwindcss init -p

这一步会做两件事：

1. 创建 postcss.config.js，配置 Tailwind CSS 和其他 PostCSS 插件；
2. 创建 tailwind.config.js，配置扫描规则、主题、插件等。

为了让 Tailwind CSS 在打包时生成对应的样式，需要正确配置 content 字段。下面的配置会扫描 index.html 以及 src 目录下的 Vue、JavaScript、TypeScript、JSX 和 TSX 文件：

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    './index.html',
    './src/**/*.{vue,js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Vite 创建的项目通常使用 ESM，因此这里使用 export default。如果项目明确使用 CommonJS，则可以改为 module.exports =，但两种写法不要混用。postcss.config.js 也应遵循同样的模块格式；如果要继续使用 CommonJS，可以将文件命名为 postcss.config.cjs。

Tailwind CSS 不会生成一个包含所有可能样式的全量样式包，而是根据扫描到的 class 生成对应的样式代码，这通常可以减小最终 CSS 文件的体积。

不过，Tailwind CSS 只能识别构建时能够静态分析到的完整 class 名称。下面这种动态拼接方式可能无法生成对应样式：

const color = 'red'
const className = `bg-${color}-500`

更稳妥的写法是使用完整 class 名称映射：

const colorClassMap = {
  red: 'bg-red-500',
  blue: 'bg-blue-500',
}

const className = colorClassMap[color]

参考文档：Content configuration

引入 Tailwind CSS 的基本指令

在 src/tailwind.css 中写入：

@tailwind base;
@tailwind components;
@tailwind utilities;

然后在 main.js 或 main.ts 中引入：

import './tailwind.css'

完成这些步骤后，就可以开始使用 Tailwind CSS 的 utility class 了。

1.2 Tailwind CSS v4：Vite + Vue

Tailwind CSS v4 推荐使用官方 Vite 插件。新项目不要再按照 v3 的方式执行 tailwindcss init -p，也不需要手动维护传统的 content 配置。

安装依赖：

pnpm add -D tailwindcss @tailwindcss/vite

在 vite.config.js 或 vite.config.ts 中加入插件：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import tailwindcss from '@tailwindcss/vite'

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

在入口 CSS 文件中引入 Tailwind CSS：

@import 'tailwindcss';

然后在入口文件中引入该 CSS 文件：

import './style.css'

如果项目使用 PostCSS 而不是 Vite 插件，则安装 @tailwindcss/postcss，并在 postcss.config.mjs 中配置：

pnpm add -D tailwindcss @tailwindcss/postcss postcss

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

v4 安装文档：Using Vite | Using PostCSS

二、开始使用

现在，你可以开始使用 Tailwind CSS 的语法了：

<template>
  <div class="h-32 w-32 bg-blue-500"></div>
</template>

如上代码会在页面中显示一个正方形的蓝色盒子。

Tailwind CSS 语法检索技巧

Tailwind CSS 的基本思路是将常见的样式属性拆分成 utility class。因此，在官网检索想要的样式 class 时，按照样式的语义来检索通常是效率最高的方式，例如：

Border Radius

三、自定义 class 中使用 Tailwind CSS 语法

有时候，你可能会因为重复的元素而不得不自定义一个 class。例如，下面的写法中，多个元素重复使用了相同的 class：

<div class="p-2 font-semibold text-gray-900">首页</div>
<div class="p-2 font-semibold text-gray-900">学习 Tailwind CSS</div>
<div class="p-2 font-semibold text-gray-900">Tailwind CSS 的设计哲学</div>
<div class="p-2 font-semibold text-gray-900">最佳实践</div>

这类写法虽然直观，但当同一组 class 在很多地方重复出现时，维护起来会比较麻烦。此时，可以给每个元素一个具有语义的 class：

<div class="menu">首页</div>
<div class="menu">学习 Tailwind CSS</div>
<div class="menu">Tailwind CSS 的设计哲学</div>
<div class="menu">最佳实践</div>

Tailwind CSS 提供了 @apply 语法，可以将已有的 utility class 应用到自定义 class 中：

.menu {
  @apply p-2 font-semibold text-gray-900;
}

需要注意：

1. @apply 适合用于具有明确语义、需要重复使用的组件样式，不要为了每一个一次性样式都创建一个自定义 class；
2. @apply 不一定会让 CSS 文件更小。是否使用它，应该优先考虑可读性、复用边界和组件维护成本；
3. 如果只是重复渲染同一组数据，优先使用循环，而不是复制大量 HTML。

例如：

<template>
  <div
    v-for="menu in ['首页', '学习 Tailwind CSS', 'Tailwind CSS 的设计哲学', '最佳实践']"
    :key="menu"
    class="p-2 font-semibold text-gray-900"
  >
    {{ menu }}
  </div>
</template>

这样未来维护时，样式和内容都更加集中。

关于样式复用的更多信息，可参考：Reusing styles

如果进行的是组件级别的抽象，并且需要让使用者覆盖 class，可以通过组件的 class 属性、组件参数或 CSS 变量提供覆盖能力，并不一定只能使用自定义 class。组件级别的 class 命名仍然可以参考 BEM 规范。

四、自定义样式中使用 Tailwind CSS 的主题值

大多数情况下，我们可以组合使用 Tailwind CSS 的 utility class 来解决问题。但如果确实需要编写自定义 CSS，也可以在 Tailwind CSS v3 的 PostCSS 流程中使用 theme() 函数读取 tailwind.config.js 中的主题值。

比如，希望为某个元素添加一个上边框，并使用 Tailwind CSS 默认主题中的 gray-200：

.bordered-box {
  border-top: 1px solid theme('colors.gray.200');
}

以上代码在 Tailwind CSS v3 中会被编译为类似下面的 CSS：

.bordered-box {
  border-top: 1px solid #e5e7eb;
}

theme() 是构建阶段的函数，不是浏览器运行时的 CSS 变量。它只有在 CSS 经过 Tailwind CSS 处理时才会生效；如果直接把这段 CSS 交给浏览器，浏览器无法识别 theme()。

此外，不建议为了使用一个颜色就过度依赖 theme()。如果这个值本身就是稳定的设计令牌，也可以在项目中统一定义 CSS 变量或主题配置，以便后续维护。

参考文档：Functions and directives

五、使用 Tailwind CSS 配置之外的值

有时候，你不得不使用一些超出 Tailwind CSS 默认配置之外的值。例如：

在页面绘制一个宽 139px、高 77px、颜色为 #165DFF 的盒子。

如果直接写 CSS，可以这样实现：

.arbitrary-box {
  width: 139px;
  height: 77px;
  background-color: #165DFF;
}

如果希望继续使用 utility class，可以使用任意值语法：

<div class="h-[77px] w-[139px] bg-[#165DFF]"></div>

使用这种方法有两个好处：

1. 不需要离开 HTML，仍然可以使用 Tailwind CSS 的开发方式；
2. 相同的 class 通常只会生成一份样式规则，例如多个 w-[139px] 不会为每个元素重复生成一份 CSS。

尽管任意值可以优雅地解决临时需求，但这种“魔法值”不应在项目中大量使用。如果某个值具有明确的设计含义，最好将它加入主题配置或设计令牌中，以便统一维护。

参考文档：Using arbitrary values

六、响应式设计

Tailwind CSS 的响应式设计遵循 mobile-first（移动端优先） 原则。没有设置断点的 class 作用于所有尺寸，带有断点前缀的 class 则从该断点及更大的屏幕开始生效。

例如，先定义一个绿色盒子：

<div class="responsive-box h-32 w-32 bg-green-500"></div>

如果使用传统 CSS，需要在 768px 以上将它变为蓝色：

@media (min-width: 768px) {
  .responsive-box {
    @apply bg-blue-500;
  }
}

这里使用 .responsive-box 而不是直接选择 div，可以避免影响页面中的其他元素。

使用 Tailwind CSS，只需要在 class 上添加 md: 前缀：

<div class="h-32 w-32 bg-green-500 md:bg-blue-500"></div>

这段代码表示：

• 默认显示绿色；
• 在最小宽度为 md 的屏幕上显示蓝色；
• Tailwind CSS v3 和 v4 的默认 md 断点都是 768px，但自定义主题时应以项目配置为准。

常见断点可以参考官方文档：Responsive design

使用最大宽度断点

还可以结合任意值语法，完成更具体的响应式需求。例如：

让盒子在 1300px 以下（包含 1300px）显示绿色，超过 1300px 显示蓝色。

<div class="h-32 w-32 bg-blue-500 max-[1300px]:bg-green-500"></div>

max-[1300px]: 表示最大宽度为 1300px 时生效，因此在 1300px 及以下显示绿色，在更宽的屏幕上显示蓝色。该写法需要使用支持任意值断点的 Tailwind CSS 版本。

七、暗黑模式

7.1 Tailwind CSS v3 的 class 模式

在 Tailwind CSS v3 中，如果希望通过手动添加 class 控制暗黑模式，可以在 tailwind.config.js 中配置：

/** @type {import('tailwindcss').Config} */
export default {
  darkMode: 'class',
  // 其他配置...
}

然后在元素上同时写默认样式和 dark: 样式：

<div class="h-32 w-32 bg-blue-500 dark:bg-green-500"></div>

dark:bg-green-500 只有在该元素自身或祖先元素带有 dark class 时才会生效。例如：

<html class="dark">
  <body>
    <div class="h-32 w-32 bg-blue-500 dark:bg-green-500"></div>
  </body>
</html>

实际项目中，通常通过 JavaScript 切换 html 元素上的 dark class：

const root = document.documentElement

function setDarkMode(enabled) {
  root.classList.toggle('dark', enabled)
}

setDarkMode(true)

在 Vue 中，可以将开关状态与 localStorage 结合：

<script setup>
import { onMounted, ref, watch } from 'vue'

const isDark = ref(false)

function applyTheme(value) {
  document.documentElement.classList.toggle('dark', value)
  localStorage.setItem('theme', value ? 'dark' : 'light')
}

watch(isDark, (value) => {
  if (typeof window !== 'undefined') {
    applyTheme(value)
  }
})

onMounted(() => {
  isDark.value = localStorage.getItem('theme') === 'dark'
  applyTheme(isDark.value)
})
</script>

<template>
  <button type="button" @click="isDark = !isDark">
    切换暗黑模式
  </button>
</template>

在 SSR 场景中，访问 localStorage 和 document 应放在客户端生命周期或客户端专用代码中，避免服务端渲染时报错。

参考文档：Dark mode

八、覆盖和扩展 Tailwind CSS 配置

Tailwind CSS 的默认配置与团队的 UI 规范有出入时，可以通过配置文件扩展主题。

8.1 扩展文本颜色

下面使用配置为文本增加 Arco Design 风格的颜色：

/** @type {import('tailwindcss').Config} */
export default {
  theme: {
    extend: {
      textColor: {
        primary: '#1D2129',
        regular: '#4E5969',
        secondary: '#86909C',
        disabled: '#C9CDD4',
      },
    },
  },
}

然后就可以使用：

<span class="text-primary">主色</span> /
<span class="text-regular">常规色</span> /
<span class="text-secondary">次要色</span> /
<span class="text-disabled">禁用色</span>

效果如下：

主色 / 常规色 / 次要色 / 禁用色

theme.extend 表示在默认主题的基础上扩展；如果直接使用 theme 而不写 extend，可能会覆盖对应的默认配置。对于需要同时用于背景色、边框色和文本色的设计令牌，也可以考虑统一配置到 colors 中。

更多配置方式可参考：Theme configuration

九、是否需要使用 CSS 预处理器

在开始本小节前，可以先思考一个问题：

Sass、Less、Stylus 等预处理器为我们带来了什么？

在没有预处理器时，CSS 代码可能是这样：

.foo {
  font-size: 12px;
}

.foo .bar {
  font-size: 14px;
}

使用预处理器后，可以使用嵌套语法：

.foo {
  font-size: 12px;

  .bar {
    font-size: 14px;
  }
}

预处理器在嵌套语法、变量、常用函数和逻辑处理等方面具有优势，可以提高编写 CSS 的效率。

但是，当我们使用 Tailwind CSS 时，很多样式可以直接通过 utility class 表达。对于不需要变量、复杂函数或预处理器特性的项目，确实可以不再额外引入 Sass、Less 或 Stylus。

这并不意味着预处理器一定不能使用。如果项目已经大量使用 Sass，或者确实需要复杂的计算、变量和组织能力，可以继续使用，但要注意预处理器与 Tailwind CSS 的处理顺序和语法冲突。

9.1 Tailwind CSS v3 中使用嵌套语法

Tailwind CSS v3 提供了 tailwindcss/nesting 兼容插件。配置时需要确保它位于 tailwindcss 插件之前：

export default {
  plugins: {
    'tailwindcss/nesting': {},
    tailwindcss: {},
    autoprefixer: {},
  },
}

注意，不能把 tailwindcss: {} 写在前一行的 // 注释后面，否则它会被注释掉，Tailwind CSS 就不会执行。

9.2 Tailwind CSS v4 中的嵌套语法

Tailwind CSS v4 更推荐使用原生 CSS 嵌套和官方构建流程，不要直接照搬 v3 的 tailwindcss/nesting 配置。若项目使用 Sass、Less 或 Stylus，应该先确认对应预处理器与 Tailwind CSS 的兼容方式。

例如，在 Sass 文件中使用名为 theme 的函数或其他特殊语法时，预处理器可能会先处理它，从而与 Tailwind CSS 的构建阶段产生不同的结果。遇到这类问题时，可以将相关样式移动到普通 CSS/PostCSS 文件，或改用项目统一的 CSS 变量。

十、常见问题和最佳实践

1. 锁定 Tailwind CSS 版本。 Tailwind CSS v3 和 v4 的安装命令、配置文件和 CSS 指令并不完全相同，不要只复制命令而忽略版本。
2. 保证入口 CSS 被引入。 配置正确但页面没有样式时，先确认 tailwind.css 或 style.css 已在入口文件中引入。
3. 检查扫描路径。 v3 项目要确认 content 覆盖了实际使用 class 的文件目录。
4. 不要动态拼接不完整的 class。 使用静态 class 映射，避免构建工具无法识别。
5. 合理使用任意值。 偶尔使用 w-[139px] 没有问题，但大量使用时应考虑抽取设计令牌。
6. 谨慎使用 @apply。 它适合复用稳定的语义样式，不适合替代所有 utility class。
7. 响应式采用移动端优先。 先写默认样式，再使用 sm:、md:、lg: 等断点逐步增强。
8. 暗黑模式要同时完成配置和切换。 只写 dark: class 并不会自动进入暗黑模式。
9. 预处理器不是必选项。 是否使用 Sass、Less 或 Stylus，应根据项目实际需求决定，而不是简单地全部引入或全部移除。

总结

Tailwind CSS 的核心价值，是将常见样式拆分为可组合的 utility class，并通过构建工具生成最终 CSS。它可以减少命名和样式文件维护成本，但并不意味着所有样式都必须写在 HTML 中，也不意味着任意值和 @apply 可以无约束地使用。

在实际项目中，建议先统一 Tailwind CSS 版本和构建方式，再根据团队的设计令牌、组件边界和维护习惯决定是否扩展主题、抽取 class 或使用预处理器。

相关文档：

• Tailwind CSS v3 安装
• Tailwind CSS v4 安装
• Responsive design
• Dark mode
• Using preprocessors