tailwind-v4

Tailwind CSS v4 最佳实践

快速参考

Vite 插件设置：

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [tailwindcss()],
});

CSS 入口文件：

/* src/index.css */
@import 'tailwindcss';

@theme Inline 指令：

@theme inline {
  --color-primary: oklch(60% 0.24 262);
  --color-surface: oklch(98% 0.002 247);
}

与 v3 的主要区别

功能	v3	v4
配置	tailwind.config.js	CSS 中的 @theme
构建工具	PostCSS 插件	@tailwindcss/vite
颜色	rgb() / hsl()	oklch()（默认）
主题扩展	JS 中的 extend: {}	CSS 变量
深色模式	darkMode 配置选项	CSS 变体

@theme 指令模式

default（标准模式）

生成可在其他位置引用的 CSS 变量：

@theme {
  --color-brand: oklch(60% 0.24 262);
}

/* Generates: :root { --color-brand: oklch(...); } */
/* Usage: text-brand → color: var(--color-brand) */

注意：你也可以显式使用 @theme default，将主题值标记为可由非默认 @theme 声明覆盖。

inline

直接内联值，不使用 CSS 变量（性能更好）：

@theme inline {
  --color-brand: oklch(60% 0.24 262);
}

/* Usage: text-brand → color: oklch(60% 0.24 262) */

reference

将值内联为回退值，但不生成 CSS 变量：

@theme reference {
  --color-internal: oklch(50% 0.1 180);
}

/* No :root variable, but utilities use fallback */
/* Usage: bg-internal → background-color: var(--color-internal, oklch(50% 0.1 180)) */

OKLCH 颜色格式

OKLCH 可提供感知均匀的颜色，在不同色相之间保持更好的一致性：

oklch(L% C H)

• L（亮度）：0%（黑色）到 100%（白色）
• C（色度）：0（灰色）到约 0.4（鲜艳）
• H（色相）：0-360 度（红色 → 黄色 → 绿色 → 蓝色 → 洋红色）

示例：

--color-sky-500: oklch(68.5% 0.169 237.323);  /* Bright blue */
--color-red-600: oklch(57.7% 0.245 27.325);   /* Vibrant red */
--color-zinc-900: oklch(21% 0.006 285.885);   /* Near-black gray */

CSS 变量命名

Tailwind v4 使用双连字符 CSS 变量命名约定：

@theme {
  /* Colors: --color-{name}-{shade} */
  --color-primary-500: oklch(60% 0.24 262);

  /* Spacing: --spacing multiplier */
  --spacing: 0.25rem;  /* Base unit for spacing scale */

  /* Fonts: --font-{family} */
  --font-display: 'Inter Variable', system-ui, sans-serif;

  /* Breakpoints: --breakpoint-{size} */
  --breakpoint-lg: 64rem;

  /* Custom animations: --animate-{name} */
  --animate-fade-in: fade-in 0.3s ease-out;
}

无需配置文件

Tailwind v4 不再需要配置文件：

• 无需 tailwind.config.js——改用 CSS 中的 @theme
• 无需 postcss.config.js——使用 @tailwindcss/vite 插件
• 支持 TypeScript——添加 @types/node 以解析路径

{
  "devDependencies": {
    "@tailwindcss/vite": "^4.0.0",
    "@types/node": "^22.0.0",
    "tailwindcss": "^4.0.0",
    "vite": "^6.0.0"
  }
}

渐进式展开

• 设置与安装：参见 references/setup.md，了解 Vite 插件配置、软件包设置和 TypeScript 配置
• 主题与设计令牌：参见 references/theming.md，了解 @theme 模式、调色板、自定义字体和动画
• 深色模式策略：参见 references/dark-mode.md，了解媒体查询、基于类和基于属性的方法

检查项（设置验证）

在建议使用 @theme 选项、OKLCH 令牌或 v4 工具类之前，请确认项目确实采用了 v4 集成方式：

1. 构建配置：Vite 配置从 @tailwindcss/vite 加载 tailwindcss()，且 CSS 入口文件使用 @import 'tailwindcss'。如果不满足，请先停止操作，按照 references/setup.md 修复配置。
2. 主版本号：package.json 中的 tailwindcss（使用 Vite 时还包括 @tailwindcss/vite）主版本号为 4，而非仅使用 v3 PostCSS 的工具链。
3. 主题来源：新的主题令牌应定义在 CSS 的 @theme / @theme inline 中，而非 tailwind.config.js 的 extend（v3）。如果主题仍由 v3 配置驱动，应优先迁移集成配置，而不是调整令牌。

选择指南

何时使用 @theme inline 或 default

使用 @theme inline：

• 性能更好（无 CSS 变量开销）
• 不会改变的静态颜色值
• 包含多个值的动画关键帧
• 需要直接内联值的工具类

使用 @theme（default）：

• 使用 JavaScript 实现动态主题
• 在自定义 CSS 中引用 CSS 变量
• 根据上下文变化的值
• 更便于调试（在 DevTools 中检查 CSS 变量）

何时使用 @theme reference

使用 @theme reference：

• 提供回退值，同时避免 CSS 变量开销
• 即使未定义变量也应正常工作的值
• 在保留工具类支持的同时减少 :root 的冗余
• 与 inline 结合，实现值的直接替换

常见模式

双层变量系统

将语义变量映射到设计令牌：

@theme {
  /* Design tokens (OKLCH colors) */
  --color-blue-600: oklch(54.6% 0.245 262.881);
  --color-slate-800: oklch(27.9% 0.041 260.031);

  /* Semantic mappings */
  --color-primary: var(--color-blue-600);
  --color-surface: var(--color-slate-800);
}

/* Usage: bg-primary, bg-surface */

自定义字体配置

@theme {
  --font-display: 'Inter Variable', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', ui-monospace, monospace;

  --font-display--font-variation-settings: 'wght' 400;
  --font-display--font-feature-settings: 'cv02', 'cv03', 'cv04';
}

/* Usage: font-display, font-mono */

动画关键帧

@theme inline {
  --animate-beacon: beacon 2s ease-in-out infinite;

  @keyframes beacon {
    0%, 100% {
      opacity: 1;
      transform: scale(1);
    }
    50% {
      opacity: 0.5;
      transform: scale(1.05);
    }
  }
}

/* Usage: animate-beacon */