Tailwind CSS配置详解：读懂 tailwind.config.js

Tailwind CSS之所以高度灵活，核心就在于 tailwind.config.js 配置文件。在Tailwind CSS3项目中，项目根目录下的这份JS文件，是整个框架的“控制面板”，颜色、间距、断点、暗色模式、插件都在这里定义。Tailwind4虽然支持直接在CSS内写配置，但依然兼容这份JS文件，只是不再自动读取。

执行下面命令，即可自动生成一份基础的配置模板：

npx tailwindcss init

生成出来的基础骨架长这样：

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./src/**/*.{html,js,vue}"],
  theme: {
    extend: {},
  },
  plugins: [],
}

整个文件分为四大核心板块：content、theme、顶层配置（如darkMode）、plugins。

content：告诉框架去哪里找你的代码

content 是Tailwind3最容易踩坑的配置项，作用是告诉编译器：哪些文件里面写了Tailwind的工具类。

Tailwind编译的时候，会扫描数组内填写的全部文件，提取里面用到的class，只把真正用到的样式输出到最终CSS，删掉所有没有使用的工具类，实现CSS体积压缩。

content: [
  "./index.html",
  "./src/**/*.{html,js,ts,jsx,tsx,vue}"
]

./src/**/*.{html,js} 是glob通配写法：**代表匹配所有子文件夹，{}代表匹配多种后缀。

新手高频问题：页面完全没有样式，90%是content路径写错，编译器找不到你的模板文件，最终输出空的CSS。
注意：Tailwind4不再需要手动配置content，框架会自动扫描项目源码文件。

theme：定义整套设计系统

theme 掌管项目全部设计规范，颜色、字体、圆角、间距、响应式断点、阴影、动画全部在这里设置。这里有一个非常关键的知识点：theme直接写配置，会完全覆盖框架默认值；写在theme.extend里面，则是在保留默认配置的基础上新增自定义内容。

extend：推荐新手优先使用

绝大多数场景我们只需要新增项目自己的主题，不想丢掉Tailwind自带的颜色、间距，就写在extend内部。

theme: {
  extend: {
    // 新增业务主题色
    colors: {
      primary: '#1D4ED8',
      brand: {
        light:'#93C5FD',
        DEFAULT:'#3B82F6',
        dark:'#1E40AF'
      }
    },
    // 新增自定义间距
    spacing: {
      '18':'4.5rem'
    },
    // 新增响应式断点
    screens: {
      '3xl':'1600px'
    },
    borderRadius: {
      'xl':'1.5rem'
    }
  }
}

写完之后，就可以直接使用 text-primary、bg-brand-dark、mt‑18、3xl:text‑4xl 这类工具类。

直接覆盖全部默认值

如果你的项目要彻底抛弃框架自带调色板，全部使用自己的一套设计规范，可以直接在theme的一级属性写配置，此时原有默认值全部失效。

theme: {
  colors: {
    blue:'#1fb6ff',
    orange:'#ff7849'
  }
}

上面例子中，框架原本自带的red、green、gray全部消失，项目只能使用这里定义的颜色。适合设计规范极其严格，不允许开发随意使用框架自带色值的业务。

theme下面可配置的内容非常丰富，除颜色之外，还可以自定义字号、字重、行高、阴影、z-index层级、过渡动画时长、网格布局规则等。

darkMode：暗色模式开关（顶层配置）

darkMode 是写在配置文件顶层，不是写在theme内部，有两种模式可选。

darkMode:'media'（默认）
读取操作系统的深色模式设置，系统开启暗色主题，页面dark:前缀样式自动生效，不需要写JS代码。缺点是页面内不能做切换按钮，只能跟随系统。
darkMode:'class'（业务项目更常用）
不会自动跟随系统，当<html>标签上面手动加上dark这个class时，所有dark:的样式才会生效。我们可以写JS做切换按钮，由用户手动切换亮/暗色模式。

module.exports = {
  darkMode: 'class',
  theme:{
    extend:{}
  }
}

plugins：扩展框架能力

plugins数组用来加载官方、社区第三方插件，也可以自己编写插件生成全新工具类。

引入现成插件

官方常用插件有表单美化@tailwindcss/forms、文章排版@tailwindcss/typography等，安装包之后直接引入。

plugins: [
  require('@tailwindcss/forms'),
  require('@tailwindcss/typography')
]

手写简单自定义插件

可以通过插件API，自己生成全新的原子工具类。比如新增文字阴影工具类：

const plugin = require('tailwindcss/plugin')
module.exports = {
  plugins: [
    plugin(function ({ addUtilities }) {
      addUtilities({
        '.text-shadow': {
          textShadow: '2px 2px 4px rgba(0,0,0,0.5)'
        }
      })
    })
  ]
}

配置完成，页面就可以直接写 class="text-shadow" 使用。

其他补充：variants变体配置

variants 用来扩展哪些CSS状态可以生成对应的修饰符。例如希望disabled禁用状态可以作用在透明度工具类上，就可以做扩展：

variants: {
  extend: {
    opacity: ['disabled']
  }
}

配置后就可以写 disabled:opacity‑50，元素被禁用时透明度变为0.5。

容易踩坑的配置小结

区分覆盖与扩展：绝大多数业务请写在theme.extend，不要直接写在theme一级，否则会把框架自带全部颜色、间距清空。
content路径必须正确，路径写错会直接导致样式不生效，v3版本这一步不可省略。
darkMode是顶层字段，不要写到theme里面，否则暗色模式完全不会生效。
修改配置文件之后，需要重启Tailwind监听编译进程，修改才会生效。
Tailwind4虽然推荐CSS内使用@theme语法做配置，但为了兼容老项目，依然支持tailwind.config.js，需要显式声明加载该配置文件。

小结

tailwind.config.js 相当于把项目的设计规范统一收拢在一处管理。颜色、断点、暗色模式、插件全部在这里管控，保证团队开发时所有人使用同一套设计尺度，避免开发人员随意写死颜色、尺寸带来的维护混乱。理解content、theme.extend、darkMode、plugins四大块，就可以处理绝大多数自定义需求。

Tailwind CSS 配置