跳到主要内容

自定义配置

Tailwind CSS v4 带来了革命性的 CSS-first 配置方式，你可以在 CSS 文件中直接配置主题、自定义工具类和变体，无需 JavaScript 配置文件。本章将详细介绍如何自定义 Tailwind CSS。

CSS-first 配置理念​

Tailwind CSS v4 的核心设计目标是让框架感觉更像原生 CSS，而不是一个 JavaScript 库。所有配置都在 CSS 中完成，这意味着：

  • 无需额外的配置文件
  • 配置与样式在同一个地方
  • 更好的 IDE 支持和语法高亮
  • CSS 变量自动生成，可在任何地方使用

@theme 指令​

@theme 指令是 Tailwind CSS v4 配置的核心，用于定义影响工具类生成的主题变量。

基本语法​

@import "tailwindcss";

@theme {
  --font-display: "Satoshi", sans-serif;
  --color-brand-500: oklch(0.7 0.15 165);
  --breakpoint-3xl: 1920px;
}

为什么使用 @theme 而不是 :root？​

主题变量不只是普通的 CSS 变量，它们还会指示 Tailwind 创建对应的工具类。例如，定义 --color-mint-500 会自动生成 bg-mint-500、text-mint-500、border-mint-500 等工具类。

使用 :root 定义的是普通 CSS 变量，不会生成工具类：

/* 这会生成工具类 */
@theme {
  --color-brand-500: oklch(0.7 0.15 165);
}

/* 这不会生成工具类，只是普通变量 */
:root {
  --custom-value: 10px;
}

主题变量命名空间​

每个命名空间对应一类工具类或变体：

命名空间生成的工具类
--color-*颜色类：bg-red-500、text-sky-300 等
--font-*字体族：font-sans、font-mono 等
--text-*字体大小：text-xl、text-sm 等
--font-weight-*字重：font-bold、font-medium 等
--tracking-*字间距：tracking-wide、tracking-tight 等
--leading-*行高：leading-tight、leading-loose 等
--breakpoint-*响应式断点：sm:*、md:* 等
--container-*容器查询断点和尺寸：@sm:*、max-w-md 等
--spacing-*间距和尺寸：px-4、max-h-16 等
--radius-*圆角：rounded-sm、rounded-lg 等
--shadow-*阴影：shadow-md、shadow-lg 等
--inset-shadow-*内阴影：inset-shadow-xs 等
--drop-shadow-*投影滤镜：drop-shadow-md 等
--blur-*模糊滤镜：blur-md 等
--perspective-*透视：perspective-near 等
--aspect-*宽高比：aspect-video 等
--ease-*过渡曲线：ease-out 等
--animate-*动画：animate-spin 等

自定义颜色​

添加单个颜色​

@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
}

使用：

<button class="bg-primary text-white">主按钮</button>
<button class="bg-secondary text-white">次按钮</button>

添加颜色系列​

定义完整的色阶可以获得更多灵活性：

@import "tailwindcss";

@theme {
  --color-brand-50: oklch(0.99 0.01 165);
  --color-brand-100: oklch(0.98 0.02 165);
  --color-brand-200: oklch(0.95 0.05 165);
  --color-brand-300: oklch(0.90 0.08 165);
  --color-brand-400: oklch(0.82 0.12 165);
  --color-brand-500: oklch(0.70 0.15 165);
  --color-brand-600: oklch(0.58 0.14 165);
  --color-brand-700: oklch(0.48 0.12 165);
  --color-brand-800: oklch(0.38 0.10 165);
  --color-brand-900: oklch(0.30 0.08 165);
  --color-brand-950: oklch(0.20 0.06 165);
}

使用：

<div class="bg-brand-500 hover:bg-brand-600 text-white">
  使用品牌色
</div>
<div class="bg-brand-100 text-brand-800">
  浅色背景配深色文字
</div>

使用 OKLCH 颜色​

Tailwind CSS v4 默认使用 OKLCH 颜色空间，它比传统的 RGB/HSV 能表示更广的色域，颜色更鲜艳生动。

OKLCH 格式为 oklch(亮度 饱和度 色相)：

@theme {
  /* 亮度: 0-1 (黑到白) */
  /* 饱和度: 0-0.4 左右 (灰到鲜艳) */
  /* 色相: 0-360 (色轮角度) */
  
  --color-coral: oklch(0.70 0.18 25);    /* 珊瑚红 */
  --color-ocean: oklch(0.55 0.15 240);   /* 海洋蓝 */
  --color-forest: oklch(0.50 0.12 145);  /* 森林绿 */
  --color-sunset: oklch(0.75 0.20 50);   /* 日落橙 */
}

自定义字体​

字体族​

@import "tailwindcss";

@theme {
  --font-sans: Inter, system-ui, sans-serif;
  --font-serif: Merriweather, Georgia, serif;
  --font-mono: Fira Code, monospace;
  --font-display: "Satoshi", sans-serif;
}

使用：

<h1 class="font-display text-4xl">显示字体标题</h1>
<p class="font-sans">正文使用无衬线字体</p>
<code class="font-mono">代码使用等宽字体</code>

字体大小​

@import "tailwindcss";

@theme {
  --text-xs: 0.75rem;
  --text-xs--line-height: 1rem;
  --text-sm: 0.875rem;
  --text-sm--line-height: 1.25rem;
  --text-base: 1rem;
  --text-base--line-height: 1.5rem;
  --text-lg: 1.125rem;
  --text-lg--line-height: 1.75rem;
  --text-2xl: 1.5rem;
  --text-2xl--line-height: 2rem;
}

自定义断点​

添加新断点​

@import "tailwindcss";

@theme {
  --breakpoint-xs: 30rem;      /* 480px */
  --breakpoint-sm: 40rem;      /* 640px */
  --breakpoint-md: 48rem;      /* 768px */
  --breakpoint-lg: 64rem;      /* 1024px */
  --breakpoint-xl: 80rem;      /* 1280px */
  --breakpoint-2xl: 96rem;     /* 1536px */
  --breakpoint-3xl: 120rem;    /* 1920px */
}

使用：

<div class="grid grid-cols-1 xs:grid-cols-2 md:grid-cols-3 3xl:grid-cols-6">
  响应式网格
</div>

覆盖默认断点​

@import "tailwindcss";

@theme {
  --breakpoint-sm: 30rem;  /* 覆盖默认的 40rem */
}

自定义间距​

间距比例​

@import "tailwindcss";

@theme {
  --spacing: 0.25rem;  /* 基础单位，默认 4px */
  
  /* 或者添加具体的间距值 */
  --spacing-128: 32rem;
  --spacing-144: 36rem;
}

由于间距是动态计算的，你不需要预定义所有值。使用 p-17、mt-29 等会自动计算为 calc(var(--spacing) * 17)。

自定义动画​

定义动画​

在 @theme 中定义动画变量和关键帧：

@import "tailwindcss";

@theme {
  --animate-fade-in: fade-in 0.5s ease-out;
  --animate-slide-up: slide-up 0.3s ease-out;
  --animate-bounce-in: bounce-in 0.5s cubic-bezier(0.68, -0.55, 0.265, 1.55);
  
  @keyframes fade-in {
    0% { opacity: 0; }
    100% { opacity: 1; }
  }
  
  @keyframes slide-up {
    0% { 
      transform: translateY(20px);
      opacity: 0;
    }
    100% { 
      transform: translateY(0);
      opacity: 1;
    }
  }
  
  @keyframes bounce-in {
    0% { 
      transform: scale(0.3);
      opacity: 0;
    }
    50% { 
      transform: scale(1.05);
    }
    70% { 
      transform: scale(0.9);
    }
    100% { 
      transform: scale(1);
      opacity: 1;
    }
  }
}

使用：

<div class="animate-fade-in">淡入效果</div>
<div class="animate-slide-up">向上滑入</div>
<div class="animate-bounce-in">弹跳进入</div>

自定义阴影​

@import "tailwindcss";

@theme {
  --shadow-soft: 0 2px 15px -3px rgba(0, 0, 0, 0.07), 
                 0 10px 20px -2px rgba(0, 0, 0, 0.04);
  --shadow-inner-lg: inset 0 2px 4px 0 rgba(0, 0, 0, 0.1);
}

使用：

<div class="shadow-soft p-6 rounded-lg">柔和阴影</div>
<div class="shadow-inner-lg p-4 bg-gray-100">内阴影</div>

自定义圆角​

@import "tailwindcss";

@theme {
  --radius-4xl: 2rem;
  --radius-5xl: 2.5rem;
}

使用：

<div class="rounded-4xl bg-blue-500 p-4">大圆角</div>
<div class="rounded-5xl bg-green-500 p-4">超大圆角</div>

扩展与覆盖​

扩展默认主题​

在 @theme 中添加新变量会扩展默认主题：

@import "tailwindcss";

@theme {
  --font-script: "Great Vibes", cursive;
  --color-mint-500: oklch(0.72 0.11 178);
}

覆盖默认值​

重新定义同名变量会覆盖默认值：

@import "tailwindcss";

@theme {
  --breakpoint-sm: 30rem;  /* 覆盖默认的 40rem */
  --color-blue-500: oklch(0.65 0.20 250);  /* 覆盖默认蓝色 */
}

禁用整个命名空间​

使用 initial 禁用某个命名空间的所有默认值：

@import "tailwindcss";

@theme {
  /* 禁用所有默认颜色 */
  --color-*: initial;
  
  /* 然后定义自己的颜色 */
  --color-white: #fff;
  --color-black: #000;
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
}

使用完全自定义的主题​

禁用所有默认主题变量：

@import "tailwindcss";

@theme {
  /* 禁用所有默认主题 */
  --*: initial;
  
  /* 定义自己的设计系统 */
  --spacing: 4px;
  --font-body: Inter, sans-serif;
  --color-primary: oklch(0.72 0.11 221.19);
  --color-secondary: oklch(0.74 0.17 40.24);
}

CSS 变量的使用​

在自定义 CSS 中使用​

所有主题变量都会生成对应的 CSS 变量：

@import "tailwindcss";

@layer components {
  .card {
    background-color: var(--color-white);
    border-radius: var(--radius-lg);
    padding: calc(var(--spacing) * 4);
    box-shadow: var(--shadow-md);
  }
}

在任意值中使用​

<div class="rounded-[calc(var(--radius-xl)-1px)]">
  使用计算后的圆角值
</div>

<div class="p-[calc(var(--spacing)*3)]">
  使用计算后的间距
</div>

在 JavaScript 中使用​

// 获取 CSS 变量值
const styles = getComputedStyle(document.documentElement);
const shadow = styles.getPropertyValue("--shadow-xl");
const primaryColor = styles.getPropertyValue("--color-blue-500");

// 在动画库中使用
import { motion } from "motion/react";

<motion.div animate={{ backgroundColor: "var(--color-blue-500)" }} />

@source 指令​

默认情况下，Tailwind 会自动检测项目中的模板文件。如果需要添加额外的内容源，使用 @source 指令：

@import "tailwindcss";

/* 添加额外的内容源 */
@source "../node_modules/@my-company/ui-lib";
@source "./vendor/some-package/**/*.php";

@utility 指令​

使用 @utility 定义自定义工具类，它们会自动支持所有变体：

@import "tailwindcss";

@utility tab-4 {
  tab-size: 4;
}

@utility text-shadow {
  text-shadow: 2px 2px 4px rgba(0, 0, 0, 0.1);
}

@utility btn {
  border-radius: var(--radius-lg);
  padding: calc(var(--spacing) * 2) calc(var(--spacing) * 4);
  font-weight: var(--font-weight-semibold);
}

使用：

<pre class="tab-4">代码缩进为 4</pre>
<h1 class="text-shadow hover:text-shadow-none">带阴影的标题</h1>
<button class="btn bg-blue-500 text-white">自定义按钮</button>

@variant 指令​

定义自定义变体：

@import "tailwindcss";

/* 自定义悬停变体（使用旧的触摸设备行为） */
@custom-variant hover (&:hover);

/* 自定义数据属性变体 */
@variant data-active (&[data-active]);

/* 自定义媒体查询变体 */
@variant print (@media print);

使用：

<div class="data-active:bg-blue-500" data-active="true">
  当 data-active 存在时显示蓝色
</div>

插件系统​

Tailwind CSS v4 的插件系统更加简洁。

使用官方插件​

Tailwind v4 内置了许多之前需要插件的功能：

  • 容器查询：内置支持，无需 @tailwindcss/container-queries
  • 表单样式：@tailwindcss/forms 仍然可用
  • 排版：@tailwindcss/typography 仍然可用

安装和使用：

npm install @tailwindcss/forms @tailwindcss/typography
@import "tailwindcss";
@import "@tailwindcss/forms";
@import "@tailwindcss/typography";

创建自定义插件​

使用 JavaScript 创建更复杂的插件：

// tailwind.plugin.js
export default function plugin({ addUtilities, addVariables }) {
  addVariables({
    '--color-brand': '#3b82f6',
  });
  
  addUtilities({
    '.text-shadow-lg': {
      'text-shadow': '4px 4px 8px rgba(0, 0, 0, 0.15)',
    },
  });
}

然后在 CSS 中导入：

@import "tailwindcss";
@import "./tailwind.plugin.js";

@apply 指令​

@apply 允许你在自定义 CSS 中使用 Tailwind 的工具类：

@import "tailwindcss";

@layer components {
  .btn {
    @apply inline-flex items-center justify-center font-medium rounded-lg transition-colors;
  }
  
  .btn-primary {
    @apply bg-blue-500 text-white hover:bg-blue-600;
  }
  
  .btn-secondary {
    @apply bg-gray-200 text-gray-800 hover:bg-gray-300;
  }
}
建议

优先使用组件抽象或 CSS 变量，@apply 仅在必要时使用。过度使用 @apply 会增加 CSS 文件大小并降低可维护性。

@layer 指令​

使用 @layer 将自定义样式添加到特定层：

@import "tailwindcss";

/* 基础层：重置和默认样式 */
@layer base {
  h1 {
    font-size: var(--text-3xl);
    font-weight: var(--font-weight-bold);
  }
  
  input:focus {
    outline: 2px solid var(--color-blue-500);
  }
}

/* 组件层：可复用的组件样式 */
@layer components {
  .card {
    background-color: var(--color-white);
    border-radius: var(--radius-lg);
    box-shadow: var(--shadow-md);
  }
}

/* 工具层：单一目的的工具类 */
@layer utilities {
  .text-shadow {
    text-shadow: 2px 2px 4px rgba(0, 0, 0, 0.1);
  }
}

层的优先级​

从低到高：

  1. theme：主题变量
  2. base：基础样式
  3. components：组件样式
  4. utilities：工具类样式

@reference 指令​

在 Vue、Svelte 或 CSS 模块的 <style> 块中，使用 @reference 引用主 CSS 文件中的主题变量和工具类：

<template>
  <h1 class="custom-title">Hello World</h1>
</template>

<style>
@reference "../../app.css";

.custom-title {
  @apply text-2xl font-bold text-blue-500;
}

/* 或者直接使用 CSS 变量 */
.another-element {
  color: var(--color-blue-500);
  font-size: var(--text-2xl);
}
</style>

暗黑模式配置​

配置暗黑模式触发方式​

@import "tailwindcss";

/* 使用 class 方式（默认） */
@custom-variant dark (&:where(.dark, .dark *));

/* 使用媒体查询方式 */
@custom-variant dark (@media (prefers-color-scheme: dark));

定义暗黑模式变量​

@import "tailwindcss";

@theme {
  --color-background: #ffffff;
  --color-foreground: #0a0a0a;
}

@theme dark {
  --color-background: #0a0a0a;
  --color-foreground: #fafafa;
}

使用：

<div class="bg-background text-foreground">
  自动适配暗黑模式
</div>

完整配置示例​

@import "tailwindcss";

/* 主题配置 */
@theme {
  /* 禁用默认颜色，使用自定义调色板 */
  --color-*: initial;
  
  /* 品牌色 */
  --color-primary-50: oklch(0.99 0.01 250);
  --color-primary-100: oklch(0.97 0.02 250);
  --color-primary-200: oklch(0.92 0.05 250);
  --color-primary-300: oklch(0.85 0.08 250);
  --color-primary-400: oklch(0.75 0.12 250);
  --color-primary-500: oklch(0.65 0.18 250);
  --color-primary-600: oklch(0.55 0.18 250);
  --color-primary-700: oklch(0.45 0.15 250);
  --color-primary-800: oklch(0.35 0.12 250);
  --color-primary-900: oklch(0.25 0.08 250);
  
  /* 中性色 */
  --color-white: #ffffff;
  --color-black: #000000;
  --color-gray-50: oklch(0.985 0.002 247);
  --color-gray-100: oklch(0.967 0.003 264);
  --color-gray-200: oklch(0.928 0.006 264);
  --color-gray-300: oklch(0.872 0.01 258);
  --color-gray-400: oklch(0.707 0.022 261);
  --color-gray-500: oklch(0.551 0.027 264);
  --color-gray-600: oklch(0.446 0.03 256);
  --color-gray-700: oklch(0.373 0.034 259);
  --color-gray-800: oklch(0.278 0.033 256);
  --color-gray-900: oklch(0.21 0.034 264);
  
  /* 字体 */
  --font-sans: Inter, system-ui, sans-serif;
  --font-mono: "Fira Code", monospace;
  --font-display: "Satoshi", sans-serif;
  
  /* 自定义断点 */
  --breakpoint-3xl: 120rem;
  
  /* 自定义阴影 */
  --shadow-soft: 0 4px 20px -2px rgba(0, 0, 0, 0.1);
  
  /* 自定义动画 */
  --animate-fade-in: fade-in 0.3s ease-out;
  
  @keyframes fade-in {
    from { opacity: 0; }
    to { opacity: 1; }
  }
}

/* 暗黑模式 */
@theme dark {
  --color-background: var(--color-gray-900);
  --color-foreground: var(--color-gray-50);
}

/* 自定义工具类 */
@utility btn {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  padding: calc(var(--spacing) * 2) calc(var(--spacing) * 4);
  font-weight: var(--font-weight-medium);
  border-radius: var(--radius-lg);
  transition: all 0.15s ease;
}

/* 组件样式 */
@layer components {
  .card {
    background-color: var(--color-white);
    border-radius: var(--radius-xl);
    box-shadow: var(--shadow-md);
    padding: calc(var(--spacing) * 6);
  }
}

小结​

本章介绍了 Tailwind CSS v4 的 CSS-first 配置方式：

  • @theme 指令：定义主题变量，自动生成工具类
  • 命名空间：不同前缀对应不同类型的工具类
  • 自定义颜色：使用 OKLCH 颜色空间获得更鲜艳的颜色
  • 自定义字体、断点、间距、动画、阴影：完整的主题定制
  • CSS 变量：所有主题值自动暴露为 CSS 变量
  • @source、@utility、@variant：扩展 Tailwind 功能
  • @layer 和 @apply：组织自定义样式
  • 暗黑模式：CSS 中配置主题切换

下一章，我们将提供 Tailwind CSS 的速查表。