⚡

TailwindCSS配置Skill tailwind-configuration

Tailwind CSS配置技能专注于通过tailwind.config.js文件自定义Tailwind CSS框架，包括内容路径设置、主题扩展、插件集成和构建优化，适用于前端开发项目，关键词包括Tailwind CSS、配置、主题定制、插件、前端开发、CSS框架。

前端开发 0 次安装 0 次浏览 更新于 3/25/2026

name: tailwind-configuration user-invocable: false description: 在设置或自定义Tailwind CSS配置、主题定制、插件和构建设置时使用。涵盖tailwind.config.js设置和内容路径。 allowed-tools:

  • 读取
  • 写入
  • 编辑
  • Bash
  • Grep
  • Glob

Tailwind CSS - 配置

Tailwind CSS通过其配置文件高度可定制，允许您定义设计系统、扩展默认主题和配置插件。

关键概念

配置文件结构

tailwind.config.js（或.ts、.cjs、.mjs）文件是Tailwind定制的核心：

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/**/*.{html,js,jsx,ts,tsx}',
    './pages/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {
      // 自定义主题扩展
    },
  },
  plugins: [],
  darkMode: 'class', // 或 'media'
  prefix: '',
  important: false,
  separator: ':',
}

内容配置

content数组告诉Tailwind在哪里查找类名：

module.exports = {
  content: [
    './src/**/*.{html,js,jsx,ts,tsx}',
    './pages/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
    './app/**/*.{js,ts,jsx,tsx}',
    './public/index.html',
  ],
  // ...
}

带有转换的内容

对于动态类名，使用安全列表或内容转换：

module.exports = {
  content: {
    files: ['./src/**/*.{html,js}'],
    transform: {
      md: (content) => {
        // 从markdown中提取类
        return content
      }
    }
  },
  safelist: [
    'bg-red-500',
    'bg-green-500',
    {
      pattern: /bg-(red|green|blue)-(100|200|300)/,
    },
  ],
}

主题定制

扩展默认主题

使用theme.extend在不替换现有值的情况下添加新值：

module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#f0f9ff',
          100: '#e0f2fe',
          200: '#bae6fd',
          300: '#7dd3fc',
          400: '#38bdf8',
          500: '#0ea5e9',
          600: '#0284c7',
          700: '#0369a1',
          800: '#075985',
          900: '#0c4a6e',
          950: '#082f49',
        },
        primary: '#0ea5e9',
        secondary: '#8b5cf6',
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
        serif: ['Merriweather', 'serif'],
        mono: ['Fira Code', 'monospace'],
      },
      spacing: {
        '72': '18rem',
        '84': '21rem',
        '96': '24rem',
        '128': '32rem',
      },
      borderRadius: {
        '4xl': '2rem',
        '5xl': '2.5rem',
      },
      fontSize: {
        'xxs': '0.625rem',
      },
      boxShadow: {
        'inner-lg': 'inset 0 2px 4px 0 rgba(0, 0, 0, 0.06)',
      },
      animation: {
        'spin-slow': 'spin 3s linear infinite',
        'bounce-slow': 'bounce 2s infinite',
      },
      keyframes: {
        wiggle: {
          '0%, 100%': { transform: 'rotate(-3deg)' },
          '50%': { transform: 'rotate(3deg)' },
        }
      },
    },
  },
}

覆盖默认主题

使用theme（不带extend）替换默认值：

module.exports = {
  theme: {
    // 这会完全替换默认调色板
    colors: {
      white: '#ffffff',
      black: '#000000',
      gray: {
        100: '#f7fafc',
        // ... 自定义灰度
        900: '#1a202c',
      },
      blue: {
        500: '#0ea5e9',
      },
    },
  },
}

最佳实践

1. 使用CSS变量实现动态颜色

将Tailwind与CSS变量结合以实现运行时主题切换：

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: 'rgb(var(--color-primary) / <alpha-value>)',
        secondary: 'rgb(var(--color-secondary) / <alpha-value>)',
      },
    },
  },
}

/* globals.css */
:root {
  --color-primary: 14 165 233; /* RGB值 */
  --color-secondary: 139 92 246;
}

[data-theme='dark'] {
  --color-primary: 56 189 248;
  --color-secondary: 167 139 250;
}

2. 组织主题扩展

分组相关自定义以提高可维护性：

const colors = require('./theme/colors')
const typography = require('./theme/typography')
const spacing = require('./theme/spacing')

module.exports = {
  theme: {
    extend: {
      ...colors,
      ...typography,
      ...spacing,
    },
  },
}

3. 使用插件实现可重用模式

使用插件创建自定义实用程序：

const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addUtilities, addComponents, theme }) {
      // 添加自定义实用程序
      addUtilities({
        '.scrollbar-hide': {
          '-ms-overflow-style': 'none',
          'scrollbar-width': 'none',
          '&::-webkit-scrollbar': {
            display: 'none'
          }
        },
        '.text-balance': {
          'text-wrap': 'balance',
        }
      })

      // 添加自定义组件
      addComponents({
        '.btn': {
          padding: theme('spacing.2') + ' ' + theme('spacing.4'),
          borderRadius: theme('borderRadius.md'),
          fontWeight: theme('fontWeight.semibold'),
          '&:hover': {
            opacity: 0.8,
          }
        }
      })
    })
  ],
}

4. 配置深色模式

选择合适的深色模式策略：

module.exports = {
  // 基于类（手动控制）
  darkMode: 'class',

  // 或基于媒体查询（系统偏好）
  // darkMode: 'media',

  // 或自定义选择器
  // darkMode: ['class', '[data-theme="dark"]'],
}

5. 为生产优化

配置以减少包大小：

module.exports = {
  content: [
    './src/**/*.{html,js,jsx,ts,tsx}',
  ],
  // 在生产环境中移除未使用的样式
  purge: {
    enabled: process.env.NODE_ENV === 'production',
  },
}

示例

完整的TypeScript配置

import type { Config } from 'tailwindcss'

const config: Config = {
  content: [
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './app/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    extend: {
      colors: {
        brand: {
          DEFAULT: '#0ea5e9',
          light: '#38bdf8',
          dark: '#0284c7',
        },
      },
      fontFamily: {
        sans: ['var(--font-inter)', 'sans-serif'],
      },
      animation: {
        'fade-in': 'fadeIn 0.5s ease-in-out',
        'slide-up': 'slideUp 0.5s ease-out',
      },
      keyframes: {
        fadeIn: {
          '0%': { opacity: '0' },
          '100%': { opacity: '1' },
        },
        slideUp: {
          '0%': { transform: 'translateY(20px)', opacity: '0' },
          '100%': { transform: 'translateY(0)', opacity: '1' },
        },
      },
    },
  },
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/typography'),
    require('@tailwindcss/aspect-ratio'),
  ],
  darkMode: 'class',
}

export default config

多品牌配置

const brandColors = {
  brandA: {
    primary: '#0ea5e9',
    secondary: '#8b5cf6',
  },
  brandB: {
    primary: '#10b981',
    secondary: '#f59e0b',
  },
}

const currentBrand = process.env.BRAND || 'brandA'

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: brandColors[currentBrand].primary,
        secondary: brandColors[currentBrand].secondary,
      },
    },
  },
}

框架特定配置

Next.js

// tailwind.config.js
module.exports = {
  content: [
    './pages/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
    './app/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Vite + React

// tailwind.config.js
module.exports = {
  content: [
    './index.html',
    './src/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Vue 3

// tailwind.config.js
module.exports = {
  content: [
    './index.html',
    './src/**/*.{vue,js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

常见模式

设计令牌集成

const designTokens = {
  colors: {
    primary: {
      50: '#eff6ff',
      500: '#3b82f6',
      900: '#1e3a8a',
    },
  },
  spacing: {
    xs: '0.25rem',
    sm: '0.5rem',
    md: '1rem',
    lg: '1.5rem',
    xl: '2rem',
  },
}

module.exports = {
  theme: {
    extend: {
      colors: designTokens.colors,
      spacing: designTokens.spacing,
    },
  },
}

响应式断点定制

module.exports = {
  theme: {
    screens: {
      'xs': '475px',
      'sm': '640px',
      'md': '768px',
      'lg': '1024px',
      'xl': '1280px',
      '2xl': '1536px',
      '3xl': '1920px',
    },
  },
}

插件配置

module.exports = {
  plugins: [
    // 官方插件
    require('@tailwindcss/forms')({
      strategy: 'class', // 或 'base'
    }),
    require('@tailwindcss/typography')({
      className: 'prose',
    }),
    require('@tailwindcss/container-queries'),

    // 自定义插件
    require('./plugins/utilities'),
  ],
}

反模式

❌ 不要在多个地方硬编码值

// 错误：重复值
module.exports = {
  theme: {
    extend: {
      spacing: {
        'custom': '17px',
      },
      width: {
        'custom': '17px',
      },
      height: {
        'custom': '17px',
      },
    },
  },
}

// 正确：一致使用间距比例
module.exports = {
  theme: {
    extend: {
      spacing: {
        'custom': '17px',
      },
    },
  },
}
// 然后使用 w-custom、h-custom、p-custom 等

❌ 不要在想要替换时扩展

// 错误：意外保留默认颜色
module.exports = {
  theme: {
    extend: {
      colors: {
        // 这会添加到默认调色板，而不是替换它
        blue: { 500: '#custom-blue' }
      },
    },
  },
}

// 正确：明确替换
module.exports = {
  theme: {
    colors: {
      // 这会替换整个调色板
    },
  },
}

❌ 不要使用过于特定的内容路径

// 错误：太具体，可能会遗漏文件
module.exports = {
  content: [
    './src/components/Button.tsx',
    './src/components/Card.tsx',
    // ...数百个文件
  ],
}

// 正确：使用通配符模式
module.exports = {
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
  ],
}

❌ 不要忘记为动态类配置安全列表

// 错误：动态类不会被包含
<div className={`bg-${color}-500`}>

// 正确：添加到安全列表
module.exports = {
  safelist: [
    {
      pattern: /bg-(red|green|blue|yellow)-(500|600|700)/,
    },
  ],
}

// 更好：使用完整类名
<div className={color === 'red' ? 'bg-red-500' : 'bg-blue-500'}>

相关技能

  • tailwind-utility-classes：有效使用Tailwind的实用类
  • tailwind-components：构建可重用组件模式
  • tailwind-plugins：创建自定义Tailwind插件
  • tailwind-performance：优化Tailwind生产性能