tailwind-v4

Tailwind CSS v4

首先检测版本

这是最重要的一步。v3 和 v4 的配置方式完全不同，针对其中一个版本的指导对另一个版本来说反而会造成问题。

# Check the installed major version
npm ls tailwindcss --depth=0 2>/dev/null || grep '"tailwindcss"' package.json

信号	版本
CSS 中的 @import "tailwindcss";	v4
@tailwind base; @tailwind components; @tailwind utilities;	v3
CSS 中的 @theme { } 块	v4
带有 content: [...] 数组的 tailwind.config.js	v3（或使用兼容层的 v4 项目）
@config "./tailwind.config.js";	v4 加载旧版配置
@tailwindcss/postcss 或 @tailwindcss/vite 依赖项	v4
PostCSS 配置中需要 autoprefixer + postcss-import	v3

默认情况下，绝不要为 v4 项目编写 tailwind.config.js。 v4 从 CSS 中读取配置。手动添加的配置文件会被静默忽略，除非通过 @config 显式加载。

v4 设置

/* app.css — the single entry point */
@import "tailwindcss";

这一行取代了三个 @tailwind 指令，同时也会在内部处理 postcss-import 和 autoprefixer——请从 PostCSS 配置中移除这两项。

Vite：

// vite.config.js
import tailwindcss from "@tailwindcss/vite";
export default { plugins: [tailwindcss()] };

PostCSS：

// postcss.config.mjs
export default { plugins: { "@tailwindcss/postcss": {} } };

配置以 CSS 为先

设计令牌放在 @theme 中。每个条目都会生成对应的工具类，并且暴露一个真正的 CSS 自定义属性。

@import "tailwindcss";

@theme {
  --color-brand: oklch(0.62 0.19 250);
  --color-brand-muted: oklch(0.72 0.08 250);
  --font-display: "IBM Plex Sans", sans-serif;
  --radius-card: 14px;
  --spacing-gutter: 2.75rem;
  --ease-out-soft: cubic-bezier(0.22, 0.61, 0.36, 1);
}

--color-brand 会生成 bg-brand、text-brand、border-brand 等工具类，并且可以在任何地方通过 var(--color-brand) 读取。这个双重特性是 v4 的主要优势：令牌不再局限于 JS 配置中。

命名空间映射到工具类系列——--color-*、--font-*、--text-*、--spacing-*、--radius-*、--shadow-*、--ease-*、--animate-*、--breakpoint-*。

可以覆盖整个命名空间，或覆盖所有内容：

@theme {
  --color-*: initial;          /* drop the default palette */
  --color-ink: #18181b;
}

没有 content 数组。 v4 会自动检测源文件，同时遵循 .gitignore 并跳过二进制文件。只有在需要时才指定额外的源文件：

@source "../packages/ui/src";           /* add a path outside the project root */
@source not "../legacy";                 /* exclude */
@source inline("bg-red-500 bg-red-600"); /* the v4 replacement for safelist */

从 v3 迁移到 v4

先运行 codemod，再检查差异：

npx @tailwindcss/upgrade

这些重命名会造成静默问题：

v3	v4
shadow-sm	shadow-xs
shadow	shadow-sm
rounded-sm	rounded-xs
rounded	rounded-sm
blur-sm	blur-xs
outline-none	outline-hidden
bg-opacity-50	bg-black/50（仅支持斜杠透明度）
flex-shrink-0	shrink-0

裸用的 shadow → shadow-sm 和 rounded → rounded-sm 是最危险的一对：旧类名仍然有效，但现在表示小一档，因此 v3 代码库会在各处静默地降低一档阴影高度和圆角，而不是报错。

还需要注意其他行为变化：

• 默认边框颜色现在是 currentColor，而不是 gray-200。单独使用 border 会继承文本颜色——请显式设置颜色。
• 默认环现在是 1px currentColor，以前是蓝色的 3px。要保持 v3 的尺寸，请将 ring 改为 ring-3。
• 空间分布的选择器有所不同；相邻元素的外边距边缘情况可能会发生变化。
• 仅当设备实际支持悬停时，悬停样式才会生效。
• 变体现在按从左到右的顺序读取。

动态类名

由于扫描器仍以静态方式读取源文本，这条规则在 v3 中适用，在 v4 中依然适用：

// BROKEN — never generated
<div className={`text-${color}-500`} />

// CORRECT — complete class names, statically visible
const TONE = {
  danger: "text-red-500",
  success: "text-emerald-500",
};
<div className={TONE[tone]} />

v4 无需配置即可为许多工具类支持动态值——grid-cols-15、w-17、mt-23 等都可以任意使用。但无法动态拼接的是类名字符串。对于确实只能在运行时确定的值，请使用内联样式或 CSS 变量，而不是拼接字符串：

<div className="w-(--w)" style={{ "--w": `${pct}%` }} />

实用模式

暗色模式。 v4 默认使用 prefers-color-scheme。如需基于类名切换：

@custom-variant dark (&:where(.dark, .dark *));

提取组件的顺序。 优先使用真正的组件，而不是 @apply。需要共享 CSS 时，v4 推荐使用 @utility：

@utility card {
  border-radius: var(--radius-card);
  background: var(--color-surface);
}

大量使用 @apply 会背离工具类的初衷并增加 CSS 体积——应把它作为最后的选择，而不是首选。

任意值仍可用于一次性场景：top-[117px]、bg-[oklch(0.7_0.1_200)]、grid-cols-[1fr_auto]。

常见故障

• 类未生成 → 类名是动态构建的，或源文件位于自动检测范围之外（添加 @source）。
• tailwind.config.js 不起作用 → v4 项目未配置 @config。
• 升级后出现构建错误 → PostCSS 链中仍有 postcss-import/autoprefixer；v4 已包含这两者。
• 迁移后边框/环的显示效果不正确 → 上文提到的 currentColor 和 ring-1 默认值变更。
• 迁移后立体感略有减弱 → shadow/rounded 的重命名变化。

相关技能

• visual-style-presets — 选择一种风格方向，然后在 @theme 中定义其令牌
• beautiful-shadows — 将精确的分层阴影设为任意工具类