tailwind.config.js 常用配置项有哪些？v3/v4 怎么选？

在 Tailwind CSS v3 项目里，tailwind.config.js 通常用来控制三件事：扫描哪些源码、设计系统怎么定义、哪些框架行为需要调整。常见配置项包括 content、theme、extend、plugins、presets、darkMode、corePlugins、important、prefix、separator 和 safelist。

到了 Tailwind CSS v4，官方更推荐 CSS-first 配置，很多主题值、扫描路径和工具类扩展会写在 CSS 里，例如 @theme、@source、@utility。但旧项目迁移、共享预设、沿用已有配置时仍然可以用它，只是 v4 不会像 v3 那样自动检测配置文件，需要在 CSS 里显式引入：

css
@import "tailwindcss";
@config "../tailwind.config.js";

一个常见的 tailwind.config.js 长什么样？

javascript
module.exports = {
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx,vue,html}'],
  darkMode: 'class',
  theme: {
    extend: {
      colors: { brand: { DEFAULT: '#2563eb', dark: '#1d4ed8' } },
      spacing: { 18: '4.5rem', 128: '32rem' },
      fontFamily: { sans: ['Inter', 'system-ui', 'sans-serif'] },
    },
  },
  plugins: [require('@tailwindcss/forms'), require('@tailwindcss/typography')],
  presets: [],
  corePlugins: { preflight: true },
  important: false,
  prefix: '',
  separator: ':',
  safelist: ['prose', 'bg-red-500'],
}

不是每个项目都应该把这些配置全写上。默认值够用就别动，只有团队设计规范、第三方组件冲突或动态类名确实需要时，再加对应配置。

content：告诉 Tailwind 扫描哪些文件

content 决定 Tailwind 会从哪些文件里提取 class 名。动态拼接类名通常识别不到：

jsx
// 不推荐
<div className={`bg-${color}-500`} />

// 推荐
const colorMap = { red: 'bg-red-500 text-white', blue: 'bg-blue-500 text-white' }
<div className={colorMap[color]} />

在 Tailwind CSS v4 里，遇到 monorepo、外部 UI 包、被默认忽略的目录时，通常改用 CSS 里的 @source：

css
@import "tailwindcss";
@source "../packages/ui";

theme 和 extend 有什么区别？

theme 负责颜色、字体、间距、断点、阴影、圆角等设计 token。直接写 theme.colors、theme.spacing 通常是在覆盖默认主题。也就是说，Tailwind 原来的 red-500、blue-500、gray-100 可能会没了。

extend 的作用是保留 Tailwind 默认设计系统，再追加自己的值：

javascript
module.exports = {
  theme: {
    extend: {
      colors: { brand: '#2563eb' },
      spacing: { 18: '4.5rem' },
    },
  },
}

多数项目优先用 extend。除非公司有一套完全独立的设计系统，并明确不想使用 Tailwind 默认色板，否则不要轻易覆盖默认主题。

plugins、presets、darkMode 怎么用？

官方常用插件包括 @tailwindcss/forms、@tailwindcss/typography、@tailwindcss/aspect-ratio。多项目共享一套 Tailwind 基础配置时，可以用 presets：

javascript
module.exports = {
  presets: [require('@acme/tailwind-preset')],
  theme: { extend: { colors: { brand: '#2563eb' } } },
}

v3 里 darkMode: 'media' 适合跟随系统，darkMode: 'class' 适合手动切换。v4 里暗色模式更多会配合 CSS 变体写法处理，不要机械照搬 v3 配置。

corePlugins、important、prefix、separator、safelist 什么时候用？

corePlugins 可以关闭内置能力，最常见是关闭 preflight，但要慎用。important: true 会让生成的工具类都带上 !important，通常只在和旧 CSS、第三方组件库冲突时考虑；更温和的是 important: '#app'。prefix 适合微前端、组件库或老项目避免类名冲突，但会增加心智负担。

safelist 用来强制生成某些类，适合类名来自 CMS、数据库、接口返回值等扫描不到的场景。正则不要写太宽，否则会生成大量无用 CSS。v4 里更推荐用 CSS 的 @source inline() 表达这类保留类。

full config 和实际取舍

npx tailwindcss init --full 适合查看默认主题，不适合把完整配置复制进项目长期维护。完整配置太大，真正的业务改动很难找，升级 Tailwind 时也不容易同步默认值。

小到中型项目通常只需要 content、theme.extend、plugins、darkMode。组件库、后台系统、微前端或多项目共享配置时，再考虑 presets、prefix、important、safelist。最值得记住的是：content 决定类名能不能生成，theme.extend 决定设计系统怎么扩展，plugins 决定 Tailwind 能力怎么补充。