TailwindCSS 主题如何配置？v3 与 v4 怎么定制？

什么时候需要定制 TailwindCSS 主题？

TailwindCSS 默认提供了颜色、字号、间距、断点、圆角、阴影、动画等一整套设计基础。小项目直接用默认值就够了，但只要项目开始有品牌色、统一字号、暗色模式、多端断点，或者多个仓库共享同一套设计规范，就应该把这些东西沉淀到主题配置里。

主题配置的价值不是“把 CSS 写到另一个地方”，而是把设计规则变成可复用的工具类。比如按钮统一使用品牌主色，卡片统一使用一套圆角和阴影，页面间距统一使用固定 token，团队成员写出来的页面就不会各有各的风格。

v3：从 tailwind.config.js 开始

Tailwind v3 的主题配置集中在 tailwind.config.js。一个常见配置大概是这样：

js
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx,vue,mdx}'],
  theme: {
    extend: {
      colors: {
        brand: { 50: '#eff6ff', 500: '#3b82f6', 600: '#2563eb' },
        success: '#16a34a',
        warning: '#f59e0b',
        danger: '#dc2626'
      },
      fontFamily: {
        sans: ['Inter', 'ui-sans-serif', 'system-ui'],
        mono: ['JetBrains Mono', 'ui-monospace']
      },
      spacing: { 18: '4.5rem', 22: '5.5rem' },
      screens: { xs: '375px', '3xl': '1920px' },
      borderRadius: { card: '1rem', button: '0.625rem' },
      boxShadow: { card: '0 12px 32px rgba(15, 23, 42, 0.08)' }
    }
  },
  plugins: [require('@tailwindcss/forms'), require('@tailwindcss/typography')]
}

content 决定 Tailwind 会从哪些文件里提取 class 名。Monorepo 里经常要把共享包也加进去。不要随手写过大的 ./**/*，它可能把 node_modules、构建产物、测试快照都扫进去。

theme 是覆盖默认主题；theme.extend 是在默认主题上追加。大多数业务项目应该使用 extend，保留默认能力，只新增品牌色、特殊间距、特殊阴影。除非你真的想完全接管默认设计系统，否则不要轻易覆盖 theme.colors。

常见主题项怎么定制？

颜色最好用语义命名。比如 text-text-primary、bg-surface-muted，比到处写 text-slate-900 更容易表达设计意图。字体要考虑中文字体栈，不要只写一个英文字体。间距、圆角、阴影只把高频可复用的值放进主题，设计稿里偶尔出现一次的值可以用任意值语法。

断点也不是越多越好。项目主要面向移动端，可以补一个 xs；大屏后台或数据看板可以补 3xl。断点太多会让布局规则变得难维护。

动效也可以纳入主题：

js
extend: {
  keyframes: {
    fadeIn: { from: { opacity: '0' }, to: { opacity: '1' } },
    slideUp: { from: { opacity: '0', transform: 'translateY(8px)' }, to: { opacity: '1', transform: 'translateY(0)' } }
  },
  animation: {
    fadeIn: 'fadeIn 160ms ease-out',
    slideUp: 'slideUp 220ms ease-out'
  }
}

plugins 和 presets 怎么用？

官方常用插件包括 @tailwindcss/forms、@tailwindcss/typography、@tailwindcss/aspect-ratio。如果一个样式会在多个项目里反复出现，比如隐藏滚动条、文本渐变、容器安全区，就适合做成插件或 preset。

Monorepo 或多应用团队里，推荐把公共主题抽成 preset：

js
// packages/tailwind-preset/index.js
module.exports = {
  theme: { extend: { colors: { brand: '#2563eb' } } },
  plugins: [require('@tailwindcss/forms')]
}

业务项目里引用：

js
module.exports = {
  presets: [require('@acme/tailwind-preset')],
  content: ['./src/**/*.{js,ts,jsx,tsx}', '../../packages/ui/**/*.{js,ts,jsx,tsx}'],
  theme: { extend: { colors: { campaign: '#f97316' } } }
}

公共 preset 放品牌色、字体、圆角、基础组件规则；业务项目只放自己的活动色、特殊动画、页面级补充。

v4：用 @theme 做 CSS-first 配置

Tailwind v4 更强调 CSS-first。很多主题 token 可以直接在 CSS 里声明：

css
@import "tailwindcss";

@theme {
  --color-brand-50: #eff6ff;
  --color-brand-500: #3b82f6;
  --color-brand-600: #2563eb;
  --color-surface: #ffffff;
  --color-text-primary: #0f172a;
  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
  --spacing-18: 4.5rem;
  --radius-button: 0.625rem;
  --shadow-card: 0 12px 32px rgb(15 23 42 / 0.08);
  --breakpoint-xs: 375px;
  --animate-fade-in: fadeIn 160ms ease-out;
}

这些 token 会生成对应工具类，例如 bg-brand-600、rounded-button、shadow-card。

暗色模式建议用语义 token：

css
@theme {
  --color-page: var(--page);
  --color-card: var(--card);
  --color-text-primary: var(--text-primary);
}
:root { --page: #ffffff; --card: #f8fafc; --text-primary: #0f172a; }
.dark { --page: #020617; --card: #0f172a; --text-primary: #f8fafc; }

组件里只写 bg-page text-text-primary，切换暗色时变的是 token，不是组件结构。

full config 不是越完整越好

Tailwind v3 可以生成完整配置，用来查看默认主题很方便。但不建议把 full config 原封不动放进项目长期维护。文件太大，真正的业务改动很难找；升级 Tailwind 时，默认主题变化也不容易同步。项目里只保留自己确实定制过的部分。

一个新项目可以按这个顺序来：先确定品牌色、文本色、背景色、边框色，用语义命名；再确定字体、字号、圆角、阴影、间距；组件里尽量使用语义 token；多项目共享时，把公共 token 放到 preset 或共享 CSS 文件；动态 class 和共享组件路径提前处理好，避免生产环境缺样式。

Tailwind 主题配置写得好不好，不看配置文件有多长，而看团队能不能稳定写出同一种视觉语言。v3 用好 theme.extend、plugins、presets；v4 用好 @theme、CSS 变量和语义 token，基本就能覆盖大多数项目的定制需求。