大家好，我是jobleap.cn的小九。
Tailwind CSS 是一款原子化 CSS 框架，核心优势是通过预定义的原子类快速构建界面，无需手写大量自定义 CSS。本文基于 Next.js（App Router 版本），从环境搭建、核心 API 到综合实战，完整串联 Tailwind CSS 的常用用法。

一、环境准备：Next.js + Tailwind CSS 集成

1. 创建 Next.js 项目

# 初始化项目（选择 App Router、TypeScript、ESLint 等）
npx create-next-app@latest tailwind-next-demo
cd tailwind-next-demo

2. 安装 Tailwind 依赖

npm install -D tailwindcss postcss autoprefixer

3. 生成配置文件

npx tailwindcss init -p

执行后会生成 tailwind.config.js（Tailwind 核心配置）和 postcss.config.js（PostCSS 配置）。

4. 配置 Tailwind 作用域

修改 tailwind.config.js，指定 Tailwind 要扫描的文件路径（确保 Next.js 组件/页面能被识别）：

/** @type {import('tailwindcss').Config} */
module.exports = {
  // 暗黑模式（后续详解）
  darkMode: 'class',
  // 要处理的文件路径
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    // 主题扩展（后续详解）
    extend: {},
  },
  plugins: [],
}

5. 引入 Tailwind 基础样式

修改 app/globals.css（Next.js App Router 全局样式文件），添加 Tailwind 核心指令：

@tailwind base;    /* 基础样式重置 */
@tailwind components; /* 组件类（可自定义） */
@tailwind utilities;  /* 工具类（核心原子类） */

/* 可选：自定义全局样式 */
@layer base {
  body {
    @apply bg-white dark:bg-gray-900 text-gray-800 dark:text-gray-200;
  }
}

至此，Next.js + Tailwind CSS 环境搭建完成，接下来开始核心 API 实战。

二、Tailwind CSS 核心 API 实战（按使用频率排序）

1. 布局类：控制页面结构（最常用）

Tailwind 提供了丰富的布局原子类，覆盖 flex/grid 布局、间距、容器、尺寸等核心场景。

（1）Flex 布局（高频）

核心类：flex、flex-row/col、justify-center/between/around、items-center/start/end、flex-wrap。
示例：Next.js 组件（components/FlexDemo.tsx）

export default function FlexDemo() {
  return (
    <div className="flex flex-col md:flex-row justify-between items-center p-6 bg-gray-100 dark:bg-gray-800 rounded-lg">
      {/* 左侧区域 */}
      <div className="flex items-center mb-4 md:mb-0">
        <div className="w-10 h-10 bg-blue-500 rounded-full mr-3"></div>
        <span className="font-bold text-lg">Flex 布局示例</span>
      </div>
      {/* 右侧按钮组 */}
      <div className="flex gap-3">
        <button className="px-4 py-2 bg-green-500 text-white rounded">按钮1</button>
        <button className="px-4 py-2 bg-yellow-500 text-white rounded">按钮2</button>
      </div>
    </div>
  );
}

（2）Grid 布局（高频）

核心类：grid、grid-cols-N（N 为列数）、gap-x/y（间距）、row-span-N。
示例：博客卡片列表

export default function GridDemo() {
  const posts = [1, 2, 3, 4, 5, 6];
  return (
    <div className="container mx-auto p-6">
      <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
        {posts.map((post) => (
          <div 
            key={post} 
            className="bg-white dark:bg-gray-800 rounded-lg shadow-md p-4 border border-gray-200 dark:border-gray-700"
          >
            <h3 className="font-semibold text-xl mb-2">博客标题 {post}</h3>
            <p className="text-gray-600 dark:text-gray-400">这是博客内容，Grid 布局自适应列数</p>
          </div>
        ))}
      </div>
    </div>
  );
}

（3）间距与尺寸（高频）

• 间距类：p-N（内边距）、m-N（外边距）、px/py（水平/垂直内边距）、mx/my（水平/垂直外边距）；
• 尺寸类：w-N/h-N（宽高）、w-full/h-full（100%）、w-screen/h-screen（视口宽高）、max-w-md（最大宽度）。
  示例：

<div className="w-full max-w-4xl mx-auto p-4 my-8 h-40 bg-red-100 dark:bg-red-900/30">
  宽度100%，最大宽度4xl，水平居中，内边距4，外边距8，高度40
</div>

2. 样式类：控制视觉表现

（1）文字样式（高频）

核心类：text-N（字号）、font-light/bold/black（字重）、text-left/center/right（对齐）、text-red-500（文字颜色）、leading-N（行高）、tracking-N（字间距）。
示例：

<div className="text-lg font-semibold text-center text-blue-600 dark:text-blue-400 leading-relaxed tracking-wide">
  字号lg，半粗体，居中，蓝色文字，宽松行高，加宽字间距
</div>

（2）背景与边框（高频）

• 背景类：bg-color（背景色）、bg-opacity-N（透明度）、bg-gradient-to-r（渐变）；
• 边框类：border（边框）、border-color、rounded/N（圆角）、rounded-tl-lg（左上圆角）；
• 阴影类：shadow（默认阴影）、shadow-sm/lg/xl（阴影大小）、shadow-red-200（阴影颜色）。
  示例：

<div className="w-60 h-30 bg-gradient-to-r from-purple-500 to-pink-500 rounded-lg shadow-lg border border-purple-200 dark:border-purple-800">
  渐变背景，圆角lg，大阴影，紫色边框
</div>

（3）伪类/伪元素（高频）

核心类：hover:xxx（鼠标悬浮）、focus:xxx（聚焦）、active:xxx（点击）、disabled:xxx（禁用）、before/after:xxx（伪元素）。
示例：交互按钮

<button 
  className="px-6 py-3 bg-green-500 hover:bg-green-600 active:bg-green-700 focus:ring-2 focus:ring-green-400 disabled:bg-gray-400 text-white rounded-lg transition-all duration-300"
  disabled={false}
>
  悬浮变深，点击更深，聚焦有环，禁用变灰
</button>

3. 响应式设计（核心能力）

Tailwind 内置断点前缀，适配不同屏幕尺寸，默认断点：

• sm: 640px+
• md: 768px+
• lg: 1024px+
• xl: 1280px+
• 2xl: 1536px+

示例：响应式导航栏

export default function ResponsiveNav() {
  return (
    <nav className="bg-white dark:bg-gray-900 shadow-md">
      <div className="container mx-auto px-4">
        {/* 移动端：列布局，PC端：行布局 */}
        <div className="flex flex-col sm:flex-row justify-between items-center py-4">
          <div className="font-bold text-2xl mb-4 sm:mb-0">Tailwind Demo</div>
          {/* 移动端：堆叠，PC端：横向排列 */}
          <div className="flex flex-col sm:flex-row gap-4">
            <a href="#" className="text-gray-700 dark:text-gray-300 hover:text-blue-500">首页</a>
            <a href="#" className="text-gray-700 dark:text-gray-300 hover:text-blue-500">博客</a>
            <a href="#" className="text-gray-700 dark:text-gray-300 hover:text-blue-500">关于</a>
          </div>
        </div>
      </div>
    </nav>
  );
}

4. 自定义配置（灵活扩展）

Tailwind 默认主题满足大部分场景，可通过 tailwind.config.js 扩展/覆盖主题。

（1）自定义颜色

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        // 自定义主色
        primary: {
          50: '#f0f9ff',
          500: '#0ea5e9',
          900: '#0c4a6e',
        },
      },
    },
  },
};

使用：bg-primary-500、text-primary-900。

（2）自定义字体

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
        custom: ['"Ma Shan Zheng"', 'cursive'],
      },
    },
  },
};

使用：font-custom、font-sans。

（3）自定义断点

// tailwind.config.js
module.exports = {
  theme: {
    screens: {
      // 覆盖默认断点 + 新增断点
      xs: '360px',
      sm: '640px',
      md: '768px',
      lg: '1024px',
      xl: '1280px',
      '2xl': '1536px',
      '3xl': '1920px',
    },
  },
};

使用：xs:flex、3xl:text-4xl。

5. @apply：抽离重复类（组件化）

对于重复使用的原子类组合，可通过 @apply 抽离为自定义组件类，减少代码冗余。

示例：在 globals.css 中定义按钮组件

/* app/globals.css */
@layer components {
  .btn-primary {
    @apply px-6 py-2 bg-primary-500 text-white rounded-lg hover:bg-primary-600 focus:ring-2 focus:ring-primary-400 transition-all duration-300;
  }
  .btn-secondary {
    @apply px-6 py-2 bg-gray-200 dark:bg-gray-700 text-gray-800 dark:text-gray-200 rounded-lg hover:bg-gray-300 dark:hover:bg-gray-600;
  }
}

使用：

<button className="btn-primary">主按钮</button>
<button className="btn-secondary">次按钮</button>

6. 暗黑模式（高频需求）

Tailwind 支持两种暗黑模式：

• darkMode: 'media'：跟随系统暗黑模式；
• darkMode: 'class'：手动控制（更灵活）。

（1）配置暗黑模式

已在 tailwind.config.js 中设置 darkMode: 'class'。

（2）手动切换暗黑模式（Next.js 实现）

创建组件 components/ThemeToggle.tsx：

'use client'; // 客户端组件（需要操作DOM）
import { useEffect, useState } from 'react';

export default function ThemeToggle() {
  const [isDark, setIsDark] = useState(false);

  // 初始化：读取本地存储/系统主题
  useEffect(() => {
    const savedTheme = localStorage.getItem('theme');
    const isSystemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    const initialDark = savedTheme ? savedTheme === 'dark' : isSystemDark;
    
    if (initialDark) {
      document.documentElement.classList.add('dark');
      setIsDark(true);
    }
  }, []);

  // 切换主题
  const toggleTheme = () => {
    const newDark = !isDark;
    if (newDark) {
      document.documentElement.classList.add('dark');
      localStorage.setItem('theme', 'dark');
    } else {
      document.documentElement.classList.remove('dark');
      localStorage.setItem('theme', 'light');
    }
    setIsDark(newDark);
  };

  return (
    <button 
      onClick={toggleTheme}
      className="p-2 rounded-full bg-gray-100 dark:bg-gray-800 hover:bg-gray-200 dark:hover:bg-gray-700"
    >
      {isDark ? '🌞 切换亮色' : '🌙 切换暗色'}
    </button>
  );
}

（3）使用暗黑模式类

通过 dark:xxx 前缀适配暗黑模式样式：

<div className="bg-white dark:bg-gray-900 text-gray-800 dark:text-gray-200 p-4 rounded-lg">
  亮色模式白色背景，暗黑模式灰色背景
</div>

三、综合实战：串联所有常用 API 实现响应式页面

以下是一个综合页面（app/page.tsx），整合上述所有常用 API，实现包含导航、卡片列表、表单、主题切换的完整页面：

import ResponsiveNav from '@/components/ResponsiveNav';
import GridDemo from '@/components/GridDemo';
import ThemeToggle from '@/components/ThemeToggle';
import FlexDemo from '@/components/FlexDemo';

export default function Home() {
  return (
    <main className="min-h-screen">
      {/* 响应式导航栏 + 主题切换 */}
      <div className="relative">
        <ResponsiveNav />
        <div className="absolute top-4 right-6 sm:static sm:inline-block">
          <ThemeToggle />
        </div>
      </div>

      {/* Flex 布局示例 */}
      <div className="container mx-auto p-6">
        <FlexDemo />
      </div>

      {/* Grid 布局博客列表 */}
      <GridDemo />

      {/* 响应式表单（伪类、样式、间距） */}
      <div className="container mx-auto p-6 max-w-2xl">
        <h2 className="text-2xl font-bold mb-6 text-center">联系我们</h2>
        <form className="space-y-4">
          <div>
            <label className="block text-sm font-medium mb-1">姓名</label>
            <input 
              type="text"
              className="w-full px-4 py-2 border border-gray-300 dark:border-gray-700 rounded-lg focus:ring-2 focus:ring-primary-500 focus:border-primary-500 dark:bg-gray-800"
              placeholder="请输入姓名"
            />
          </div>
          <div>
            <label className="block text-sm font-medium mb-1">邮箱</label>
            <input 
              type="email"
              className="w-full px-4 py-2 border border-gray-300 dark:border-gray-700 rounded-lg focus:ring-2 focus:ring-primary-500 focus:border-primary-500 dark:bg-gray-800"
              placeholder="请输入邮箱"
            />
          </div>
          <div>
            <label className="block text-sm font-medium mb-1">留言</label>
            <textarea 
              className="w-full px-4 py-2 border border-gray-300 dark:border-gray-700 rounded-lg focus:ring-2 focus:ring-primary-500 focus:border-primary-500 dark:bg-gray-800 h-32"
              placeholder="请输入留言内容"
            ></textarea>
          </div>
          <button type="submit" className="btn-primary w-full sm:w-auto">提交</button>
        </form>
      </div>
    </main>
  );
}

四、优化技巧

1. 按需加载（Tailwind 自动优化）

Tailwind 会在生产环境自动移除未使用的类，无需手动配置，执行 npm run build 即可。

2. 自定义工具类

通过 @layer utilities 扩展工具类：

/* globals.css */
@layer utilities {
  .content-auto {
    content-visibility: auto;
  }
  .text-shadow {
    text-shadow: 2px 2px 4px rgba(0,0,0,0.2);
  }
}

使用：content-auto、text-shadow。

3. 禁用默认样式

若不需要 Tailwind 基础重置样式，可注释 @tailwind base，或自定义基础样式覆盖。

五、常见问题解决

1. 样式不生效：检查 tailwind.config.js 的 content 路径是否包含目标文件；
2. 暗黑模式无效：确认 darkMode 配置为 class，且根元素添加了 dark 类；
3. 自定义类不生效：使用 @layer components/utilities/base 包裹自定义类；
4. 响应式类失效：断点前缀书写顺序（如 sm:flex 而非 flex:sm）。

总结

本文基于 Next.js App Router，完整覆盖了 Tailwind CSS 的核心用法：布局类（flex/grid）、样式类（文字/背景/边框）、响应式设计、伪类、自定义配置、@apply、暗黑模式等，并通过综合实战串联所有 API。Tailwind CSS 的核心是「原子化思维」，熟练掌握常用原子类和自定义扩展，可大幅提升前端开发效率。