Tailwind CSS v4 最佳实践

快速参考

Vite 插件设置：
ts
// vite.config.ts
import tailwindcss from @tailwindcss/vite;
import { defineConfig } from vite;

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

CSS 入口文件：
css
/ src/index.css /
@import tailwindcss;

@theme 内联指令：
css
@theme inline {
--color-primary: oklch(60% 0.24 262);
--color-surface: oklch(98% 0.002 247);
}

与 v3 的主要区别

@theme 指令模式

default（标准模式）

/ 生成：:root { --color-brand: oklch(...); } /
/ 用法：text-brand → color: var(--color-brand) /

注意：你也可以显式使用 @theme default 来标记可被非默认 @theme 声明覆盖的主题值。

inline

/ 用法：text-brand → color: oklch(60% 0.24 262) /

reference

/ 没有 :root 变量，但工具类使用回退值 /
/ 用法：bg-internal → background-color: var(--color-internal, oklch(50% 0.1 180)) /

OKLCH 颜色格式

OKLCH 提供感知均匀的颜色，在不同色相间具有更好的一致性：

css
oklch(L% C H)

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

示例：
css
--color-sky-500: oklch(68.5% 0.169 237.323); / 亮蓝色 /
--color-red-600: oklch(57.7% 0.245 27.325); / 鲜艳红色 /
--color-zinc-900: oklch(21% 0.006 285.885); / 近黑色灰色 /

CSS 变量命名

Tailwind v4 使用双破折号 CSS 变量命名约定：

css
@theme {
/ 颜色：--color-{名称}-{色阶} /
--color-primary-500: oklch(60% 0.24 262);

/ 间距：--spacing 乘数 /
--spacing: 0.25rem; / 间距比例的基础单位 /

/ 字体：--font-{字体系列} /
--font-display: Inter Variable, system-ui, sans-serif;

/ 断点：--breakpoint-{尺寸} /
--breakpoint-lg: 64rem;

/ 自定义动画：--animate-{名称} /
--animate-fade-in: fade-in 0.3s ease-out;
}

无需配置文件

Tailwind v4 消除了配置文件：

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

json
{
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 inline 与 default

使用 @theme inline：

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

使用 @theme（默认）：

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

何时使用 @theme reference

使用 @theme reference：

• - 提供回退值而不产生 CSS 变量开销
• 即使变量未定义也应正常工作的值
• 减少 :root 膨胀同时保持工具类支持
• 与 inline 结合使用进行直接值替换

常见模式

双层变量系统

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

css
@theme {
/ 设计令牌（OKLCH 颜色） /
--color-blue-600: oklch(54.6% 0.245 262.881);
--color-slate-800: oklch(27.9% 0.041 260.031);

/ 语义映射 /
--color-primary: var(--color-blue-600);
--color-surface: var(--color-slate-800);
}

/ 用法：bg-primary, bg-surface /

自定义字体配置

css
@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;
}

/ 用法：font-display, font-mono /

动画关键帧

css
@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);
}
}
}

/ 用法：animate-beacon /