Nuxt 与 Tailwind CSS 集成文档

本文档详细介绍了在 Nuxt 项目中集成 Tailwind 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

最佳实践

使用 Tailwind CSS 类优先：优先使用内置类，避免编写自定义 CSS
合理组织代码：使用语义化的类名组合
利用响应式设计：充分使用 Tailwind CSS 的响应式类
自定义主题：在 @theme 规则中集中管理自定义样式
使用插件：根据需要安装 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