# Nuxt 与 Tailwind CSS 集成文档

URL: https://caijiao.org/posts/47
Source: docs/posts/47.md
Description: 本文档详细介绍了在 Nuxt 项目中集成 Tailwind CSS 的步骤和配置方法。

本文档详细介绍了在 Nuxt 项目中集成 Tailwind [CSS](/css/) 的步骤和配置方法。

## 版本信息

- Nuxt: v4.2.2
- Tailwind CSS: v4.1.18
- @tailwindcss/vite: v4.1.18

## 安装步骤

### 1. 安装 Tailwind CSS 依赖

使用 pnpm 安装 Tailwind CSS 及其相关依赖：

```bash
pnpm add -D tailwindcss @tailwindcss/vite
```

## 配置步骤

### 1. 配置 Nuxt 配置文件

在 `nuxt.config.ts` 中添加 Tailwind CSS 配置：

```typescript
// https://nuxt.com/docs/api/configuration/nuxt-config
import tailwindcss from "@tailwindcss/vite";

export default defineNuxtConfig({
  css: ["~/assets/style/index.css"],
  vite: {
    plugins: [tailwindcss()],
  },
  compatibilityDate: "2025-07-15",
  devtools: { enabled: false },
});
```

### 2. 创建 CSS 入口文件

在 `app/assets/style/index.css` 中添加 Tailwind CSS 的导入语句：

```css
@import "tailwindcss";

/* 自定义主题配置 */
@theme {
  --font-sans: "微软雅黑", "Segoe UI Emoji", "Segoe UI Symbol",
    "Noto Color Emoji";
}
```

## 主题自定义

Tailwind CSS v4 采用了新的主题配置方式，使用 `@theme` 规则在 CSS 文件中定义自定义变量。

### 1. 自定义字体

如示例中所示，您可以自定义全局字体：

```css
@theme {
  --font-sans: "微软雅黑", "Segoe UI Emoji", "Segoe UI Symbol",
    "Noto Color Emoji";
}
```

### 2. 自定义颜色

您可以扩展或覆盖默认颜色：

```css
@theme {
  --color-primary: #6b21a8;
  --color-secondary: #f97316;
}
```

### 3. 自定义间距

```css
@theme {
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  /* 更多自定义间距 */
}
```

## 使用示例

### 1. 基本使用

在 Vue 组件中直接使用 Tailwind CSS 类：

```vue
<template>
  <div class="container mx-auto p-4">
    <h1 class="text-3xl font-bold text-primary">Hello, Tailwind CSS!</h1>
    <p class="text-gray-600 mt-2">这是一个使用 Tailwind CSS 的示例。</p>
  </div>
</template>
```

### 2. 响应式设计

```vue
<template>
  <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
    <div class="bg-blue-500 text-white p-4 rounded-lg">卡片 1</div>
    <div class="bg-green-500 text-white p-4 rounded-lg">卡片 2</div>
    <div class="bg-yellow-500 text-white p-4 rounded-lg">卡片 3</div>
  </div>
</template>
```

### 3. 悬停效果

```vue
<template>
  <button
    class="bg-primary text-white px-4 py-2 rounded-lg hover:bg-primary/80 transition-colors"
  >
    悬停按钮
  </button>
</template>
```

### 4. 组合使用

```vue
<template>
  <nav class="bg-gray-800 text-white p-4">
    <div class="container mx-auto flex justify-between items-center">
      <h1 class="text-xl font-bold">我的网站</h1>
      <ul class="flex space-x-4">
        <li class="hover:text-primary transition-colors">首页</li>
        <li class="hover:text-primary transition-colors">关于</li>
        <li class="hover:text-primary transition-colors">联系</li>
      </ul>
    </div>
  </nav>
</template>
```

## 与其他 CSS 预处理器集成

如果您的项目同时使用了 SCSS/Sass 等预处理器，可以在 `nuxt.config.ts` 中进行配置：

```typescript
import tailwindcss from "@tailwindcss/vite";

export default defineNuxtConfig({
  css: ["~/assets/scss/index.scss"],
  vite: {
    plugins: [tailwindcss()],
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: `@use "~/assets/scss/variables.scss" as *;`,
        },
      },
    },
  },
});
```

然后在 `index.scss` 中导入 Tailwind CSS：

```scss
@import "tailwindcss";

// 其他 SCSS 代码
```

## 开发和构建

### 开发模式

```bash
pnpm dev
```

### 构建项目

```bash
pnpm build
```

## 最佳实践

1. **使用 Tailwind CSS 类优先**：优先使用内置类，避免编写自定义 CSS
2. **合理组织代码**：使用语义化的类名组合
3. **利用响应式设计**：充分使用 Tailwind CSS 的响应式类
4. **自定义主题**：在 `@theme` 规则中集中管理自定义样式
5. **使用插件**：根据需要安装 Tailwind CSS 插件扩展功能

## 常见问题

### 1. 样式不生效

- 检查 `nuxt.config.ts` 中是否正确配置了 Tailwind CSS 插件
- 检查 CSS 入口文件是否正确导入了 Tailwind CSS
- 确保开发服务器已重新启动

### 2. 自定义主题不生效

- 确保自定义样式在 `@theme` 规则中定义
- 检查 CSS 入口文件的加载顺序

### 3. 与其他 CSS 框架冲突

- 使用 Tailwind CSS 的 `prefix` 配置避免类名冲突
- 调整 CSS 加载顺序

## 总结

Tailwind CSS 是一个功能强大的实用优先 CSS 框架，与 Nuxt 的集成非常简单。通过本文档的步骤，您可以快速在项目中使用 Tailwind CSS，并根据需要进行自定义配置。

## 参考

[Theme variables](https://tailwindcss.com/docs/theme)