自定义配置

Tailwind 不是"黑盒"。它有一个 tailwind.config.js 文件,所有设计变量(主题色、字体、断点、间距、阴影……)都能在这里扩展或覆盖。这是把"框架"变成"你团队的设计系统"的关键——配置好后,团队成员写出来的代码天然遵循设计规范。

1. 配置文件骨架

初始化 Tailwind 时会自动生成 tailwind.config.js,长这样:

// tailwind.config.js
module.exports = {
  // 1. darkMode:控制暗色模式策略
  darkMode: 'class',  // 或 'media'(跟随系统)

  // 2. content:极重要!告诉 Tailwind 去哪些文件扫描类
  content: [
    './src/**/*.{html,js,ts,jsx,tsx,vue,astro,svelte}',
    './index.html',
  ],

  // 3. theme:设计 token(颜色/字体/间距/断点等)
  theme: {
    extend: {
      // 这里写"扩展",保留默认值
    },
  },

  // 4. plugins:官方/第三方插件
  plugins: [],
};

四个最关键字段:darkMode(暗色模式策略)、content(类扫描路径)、theme(设计 token)、plugins(插件)。

2. theme.extend vs theme:扩展 vs 覆盖

这是最重要的概念。Tailwind 默认提供了一套丰富完整的设计 token(几十种颜色、字体、间距)。你有两种方式修改:

// extend:扩展,在默认值基础上"加"。强烈推荐!
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6',         // 加一个 brand 色
        'brand-dark': '#1e40af',  // 加一个深 brand
      },
      spacing: {
        18: '4.5rem',             // 加一个 p-18 / m-18
      },
    },
  },
};

// 上面配置后:
// bg-brand、text-brand、border-brand 都能用
// p-18、m-18、w-18 都能用
// 默认的 blue-500、gray-700 等仍然全部可用

// 直接写在 theme 顶层:覆盖,默认值全部丢失!慎用
module.exports = {
  theme: {
    colors: {
      primary: '#3b82f6',
      secondary: '#10b981',
    },
    // 此时 bg-blue-500、text-gray-700 全部失效!
    // 只有 bg-primary、bg-secondary 可用
  },
};

// 99% 情况下应该用 extend,不要直接覆盖
// 除非你有意做"严格设计系统",
// 禁止使用非品牌色

99% 情况下用 extend。只在罕见场景(严格设计系统,完全禁止默认色)才用覆盖。

3. 扩展颜色

项目通常有一套品牌色。最推荐的做法是加一个色阶对象,而不是单值——这样 bg-brand-500、hover:bg-brand-600、text-brand-700 都能用,和默认色一视同仁:

// 自定义颜色:支持单值,也支持色阶对象
module.exports = {
  theme: {
    extend: {
      colors: {
        // 单值:用 bg-brand / text-brand / border-brand
        brand: '#3b82f6',

        // 色阶对象:用 bg-brand-500 / text-brand-700 等
        brand: {
          50:  '#eff6ff',
          100: '#dbeafe',
          200: '#bfdbfe',
          300: '#93c5fd',
          400: '#60a5fa',
          500: '#3b82f6',  // 主色
          600: '#2563eb',
          700: '#1d4ed8',
          800: '#1e40af',
          900: '#1e3a8a',
        },

        // 还可以引用其他颜色
        primary: '#3b82f6',
        danger:  '#ef4444',
        success: '#10b981',
        warning: '#f59e0b',
      },
    },
  },
};

获取色阶的捷径:用 uicolors.app 这类工具,输入一个主色自动生成 50~950 完整色阶。

4. 扩展字体族

用 Google Fonts 或自托管的字体时,需要扩展 fontFamily:

// 自定义字体族
module.exports = {
  theme: {
    extend: {
      fontFamily: {
        // 覆盖默认 sans(所有元素默认会用)
        sans: ['Inter', 'system-ui', 'sans-serif'],

        // 加新的字体族
        display: ['"Playfair Display"', 'serif'],   // 大标题用
        mono: ['"Fira Code"', 'monospace'],          // 代码用
        han:   ['"Noto Sans SC"', 'sans-serif'],     // 中文用
      },
    },
  },
};

// 同时在 CSS 入口引入字体:
// @import url('https://fonts.googleapis.com/css2?family=Inter&display=swap');

技巧:覆盖 sans 会让所有元素默认用新字体(因为 Tailwind 的 preflight 给 body 设了 font-sans)。加新字体族(display、mono)则用于特定场景。

5. 自定义断点

// 自定义断点
module.exports = {
  theme: {
    // extend.screens 是新增
    extend: {
      screens: {
        xs: '425px',     // 加一个超小屏(比 sm 还小)
      },
    },

    // 直接 screens 是覆盖(默认 sm/md/lg/xl/2xl 全失效)
    // screens: {
    //   sm: '500px',
    //   md: '900px',
    // },
  },
};

6. content 字段(极重要!)

content 告诉 Tailwind "去哪些文件扫描用到的类"。漏配会导致部分类不生效——这是初学者最常踩的坑:

// content 字段极重要!漏配会导致部分类不生效
module.exports = {
  content: [
    // 推荐写法:扫描所有源码目录
    './src/**/*.{html,js,ts,jsx,tsx,vue,astro,svelte}',

    // 不要忘记 index.html(Vite 项目根目录)
    './index.html',

    // 第三方组件库的源码(如果它内部用了 Tailwind 类)
    './node_modules/my-ui-lib/**/*.{js,ts}',
  ],
};

// 工作原理:
// Tailwind 在 build 时扫描这些文件,
// 把"出现在文件里的所有 utility 类名"收集起来,
// 然后只把"被用到的类"打包进最终 CSS。
// 没扫到的类不会进 CSS,导致样式失效。

常见症状:

本地开发正常,build 后某些类失效 → content 没扫到对应文件。
第三方组件库的类不生效 → 没把 node_modules 加入 content。
动态拼接的类名(如 bg-${color}-500)失效 → Tailwind 看不到完整字符串,无法识别。必须写完整字面量。

7. darkMode:暗色模式策略

两个选项:

darkMode: 'class'(推荐):手动控制,JS 给 <html> 加 .dark 类时 dark: 前缀生效。适合做"主题切换按钮"。
darkMode: 'media':跟随系统设置(prefers-color-scheme。用户系统是暗色就自动启用,无需 JS。

做产品推荐 class,给用户选择权。做技术博客可以用 media,跟随系统即可。

8. plugins:扩展能力

官方和社区提供了大量插件:

// plugins:扩展 Tailwind 能力
const typography = require('@tailwindcss/typography');
const forms      = require('@tailwindcss/forms');
const animate    = require('tailwindcss-animate');

module.exports = {
  plugins: [
    typography,  // 加 prose-* 类(美化长文)
    forms,       // 自动美化表单元素
    animate,     // 加 animate-* 类
  ],
};

// 常用官方插件:
// @tailwindcss/typography  - 长文/博客排版
// @tailwindcss/forms       - 表单元素统一样式
// @tailwindcss/aspect-ratio - 维持宽高比
// @tailwindcss/line-clamp  - 已内置,无需装

几个特别有用的官方插件:

@tailwindcss/typography:加 prose 类,自动美化长文/博客/markdown 输出。写博客站必备。
@tailwindcss/forms:统一表单元素样式,免去手写 input/select/checkbox 样式的麻烦。
@tailwindcss/aspect-ratio:维持宽高比(视频、图片占位)。
tailwindcss-animate:加动画类(淡入、滑动等)。

9. 一个完整的"团队设计系统"配置示例

把品牌色、字体、阴影、断点全部规范化,团队任何成员写代码都自动遵循:

主色 brand-500/600/700 + 中性色 primary/secondary/danger/success/warning
字体 sans(Inter)、display(Playfair)、mono(Fira Code)
圆角统一用 rounded-lg,阴影统一用 shadow-sm/md/lg
暗色模式 class 策略
装 typography + forms + animate 三个插件

这就是把 Tailwind 从"框架"变成"设计系统"的核心——配置一次,全团队受益。

10. 常见陷阱

覆盖了 theme:用 theme: { colors: {...} } 而非 theme: { extend: { colors: {...} } },默认色全部丢失。
忘记 content:类不生效。最常见。
动态类名:bg-${color}-500 不会被识别。改成完整字符串或 safelist。
safelist:某些动态类确实要写,用 safelist: ['bg-red-500', 'bg-blue-500'] 强制保留。
改完不生效:重启 dev server。配置变更有时不会热更新。

小结

记住核心要点:

99% 用 theme.extend 扩展,不要直接覆盖
content 漏配 → 类不生效
颜色用色阶对象(50~950)而非单值
暗色模式默认用 class 策略
善用插件(typography、forms)省时间
动态类名必须完整字面量或加 safelist

下一篇是最后一篇——讲 @apply 抽取组件,以及"什么时候该抽取"的工程判断。

← 上一篇状态前缀

下一篇抽取组件 →

✈️💬