Tailwind CSS V4 彻底重构了自定义样式体系，抛弃 V3 依赖 JS 配置、老旧 @layer 工具类写法，全新提供一套原生 CSS 自定义方案。V4 所有自定义样式均在 CSS 中完成，支持热更新、运行时生效、层级可控，是目前最简洁、最规范的自定义方式。

本文整合官方最新标准，全覆盖五大自定义场景：任意值内联样式、@utility 全局工具类、@custom-variant 自定义变体、@layer 分层自定义、原生CSS组件样式，附带完整避坑规则与可运行 Demo。

一、V4 自定义样式核心变化（V3→V4）

很多旧项目写法在 V4 已废弃或不推荐，核心变革必须掌握：

• ❌ V3 旧写法：依赖 tailwind.config.js 扩展工具类、变体、主题，编译时固定，无法动态修改
• ✅ V4 新规范：全部 CSS 原生指令 @utility / @custom-variant / @theme，无需 JS、热更新、支持运行时动态换肤
• ❌ V3 滥用 @layer utilities 写自定义工具
• ✅ V4 专用 @utility 指令定义全局工具，层级更安全、语义更清晰
• V4 样式层级重构：原生层叠上下文更严谨，彻底解决自定义样式覆盖混乱问题

二、最轻量：任意值内联自定义（临时样式首选）

无需任何配置，页面临时、独有、特殊样式，直接使用方括号任意值语法，支持所有 CSS 属性，零成本快速自定义。

1. 基础语法

[css属性:值]，直接写在 class 属性中

<!-- 自定义宽高、圆角、阴影 -->
<div class="w-[320px] h-[180px] rounded-[20px] shadow-[0_8px_24px_rgba(22,93,255,0.15)]">
  任意值自定义样式
</div><!-- 自定义文字样式 -->
<p class="text-[18px] leading-[1.8] text-[#165DFF]">自定义字号行高颜色</p>

2. 高级用法：支持透明度、变量、函数

<!-- 任意色 + 自定义透明度 -->
<div class="bg-[#722ED1]/70">自定义半透明颜色</div><!-- 原生 CSS 函数 -->
<div class="bg-[color-mix(in_oklch,#165DFF_60%,transparent)]">混合色彩样式</div>

最佳实践

• 适合：页面一次性、临时、特殊样式
• 不适合：全局复用样式（复用样式请用@utility）

三、全局复用：@utility 自定义工具类（V4 官方主推）

@utility 是 V4 全新专用指令，专门用来定义全局可复用工具类，替代 V3 的 @layer utilities，语法简洁、层级安全、支持嵌套 hover/active 状态。

定义后全局任意页面直接使用，和官方原生工具类优先级一致。

1. 基础单工具定义

@import "tailwindcss";/* 自定义卡片工具类 */
@utility card-base {
  padding: 1.25rem;
  border-radius: 16px;
  box-shadow: 0 4px 20px rgba(0,0,0,0.08);
  background: #fff;
}

使用：<div class="card-base">全局卡片样式</div>

2. 支持嵌套状态（hover/active）

V4 @utility 原生支持嵌套伪类、状态选择器，无需额外配置：

@utility btn-hover {
  transition: all 0.2s ease;
  &:hover {
    transform: translateY(-2px);
    box-shadow: 0 6px 16px rgba(22,93,255,0.2);
  }
  &:active {
    transform: translateY(0);
  }
}

3. 结合主题变量（推荐企业级用法）

联动 V4 @theme 变量，样式统一、支持动态换肤：

@theme {
  --color-brand: #165DFF;
  --radius-lg: 16px;
}@utility card-brand {
  background: var(--color-brand);
  border-radius: var(--radius-lg);
  color: #fff;
  padding: 1rem;
}

四、自定义修饰符：@custom-variant 自定义变体

V4 使用 @custom-variant 自定义全局变体（修饰符），类似原生 hover:、focus:，可以自定义场景前缀，适配主题、设备、父容器状态。

1. 自定义按压变体

@import "tailwindcss";/* 自定义按压效果变体 */
@custom-variant pressed {
  &:active {
    @slot;
  }
}

使用：给任意工具类添加按压状态

<button class="pressed:scale-95 pressed:opacity-80 transition">
  按压缩放透明
</button>

2. 自定义主题变体（适配暗黑/自定义主题）

/* 自定义暗夜主题变体 */
@custom-variant theme-dark {
  &:where(.dark *) {
    @slot;
  }
}

使用：theme-dark:text-white theme-dark:bg-slate-900

五、分层自定义：@layer 三层层级规范

V4 保留 @layer分层能力，用于控制自定义样式优先级，严格遵循三层层级，优先级从低到高：base → components → utilities。

⚠️ 重点：V4 禁止用 @layer utilities 定义工具类，工具类统一用 @utility，@layer 仅用于基础样式、组件样式。

1. @layer base 基础全局样式

用于重置标签、全局默认样式（html/body/h1/p 等）

@import "tailwindcss";@layer base {
  body {
    @apply bg-zinc-50 text-zinc-800;
  }
  h1 {
    @apply text-3xl font-bold;
  }
}

2. @layer components 组件复用样式

用于复杂组件样式，允许被工具类覆盖，适合封装卡片、按钮、表单组件

@layer components {
  .btn-primary {
    @apply bg-[#165DFF] text-white px-4 py-2 rounded-lg transition-all;
    &:hover {
      @apply bg-[#0E42D2];
    }
  }
}

使用：<button class="btn-primary">主按钮</button>

3. @layer utilities（V4 废弃用法）

V4 不再推荐使用该层定义工具类，统一替换为 @utility 指令，避免层级混乱、样式失效问题。

六、原生 CSS 自定义（兼容兜底）

V4 完全支持普通原生 CSS 写法，适合超复杂动画、特殊样式，可直接读取 Tailwind 主题变量。

@import "tailwindcss";/* 读取 V4 内置/自定义主题变量 */
.custom-box {
  background: var(--color-brand);
  border-radius: var(--radius-card);
  box-shadow: var(--shadow-card);
  transition: all 0.3s ease;
}
.custom-box:hover {
  filter: brightness(1.05);
}

七、V4 自定义样式选型决策表（核心规范）

八、完整可运行 V4 自定义样式 Demo

基于官方 V4 规范，整合所有自定义方式，零报错、可直接打开运行：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Tailwind V4 自定义样式完整 Demo【修复版】</title>
  <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
  <style type="text/tailwindcss">
    @import "tailwindcss";

    /* 1. 自定义主题变量 */
    @theme {
      --color-brand: #165DFF;
      --radius-card: 16px;
      --shadow-card: 0 4px 20px rgba(0,0,0,0.08);
    }

    /* 2. 全局自定义工具类 */
    @utility card-demo {
      padding: 1.5rem;
      border-radius: var(--radius-card);
      background: #fff;
      box-shadow: var(--shadow-card);
      transition: all 0.2s;
      &:hover {
        transform: translateY(-4px);
        box-shadow: 0 8px 30px rgba(22,93,255,0.15);
      }
    }

    /* 3. 自定义变体 */
    @custom-variant pressed {
      &:active {
        @slot;
      }
    }

    /* 4. 全局基础样式 */
    @layer base {
      body {
        @apply bg-zinc-50;
      }
    }

    /* 5. 组件样式：这里不再使用@apply读取自定义主题色，规避CDN @apply的bug */
    @layer components {
      .btn-demo {
        @apply text-white px-5 py-2 rounded-lg transition-all;
        background: var(--color-brand);
        &:hover {
          background: #0E42D2;
        }
      }
    }
  </style>
</head>
<body class="p-8">
  <h2 class="text-2xl font-bold text-zinc-800 mb-6">V4 五种自定义样式演示【修复】</h2>

  <!-- 1. 任意值自定义 -->
  <div class="p-4 mb-4 rounded-[12px] bg-[#f5f7fa]">
    任意值自定义样式
  </div>

  <!-- 2. @utility 全局工具 -->
  <div class="card-demo mb-4">
    @utility 自定义全局卡片
  </div>

  <!-- 3. @custom-variant 自定义变体 + 直接使用bg-brand（✅CDN可用） -->
  <button class="pressed:scale-95 btn-demo">
    自定义按压变体按钮
  </button>

  <!-- 直接在HTML class使用bg-brand ✅CDN模式下稳定 -->
  <div class="bg-brand text-white p-4 rounded-lg mt-4">
    直接写在class：bg-brand
  </div>
</body>
</html>

九、高频避坑清单（V4 专属）

• ❌ 禁止 V3 旧写法：不要用 @layer utilities 定义工具类，统一用 @utility
• ❌ 禁止嵌套错误：@utility / @custom-variant 必须顶层书写，不能嵌套在 @plugin 或其他指令内
• ✅ 样式优先级：工具类 > 组件样式 > 基础样式，符合原生 CSS 层级逻辑
• ✅ 自定义工具类优先联动 @theme 变量，方便统一维护、动态换肤
• ✅ 临时样式用任意值，复用样式用 @utility，严格区分场景，避免代码冗余
• ❌ 不要混用 V3 config 扩展工具类，V4 优先纯 CSS 自定义方案

总结

Tailwind CSS V4 彻底革新了自定义样式体系，放弃 JS 配置，全面 CSS 原生化。核心记忆点：

临时样式用任意值、全局工具用 @utility、自定义修饰符用 @custom-variant、全局基础样式用 @layer base、组件复用用 @layer components。

这套规范完全贴合官方最新标准，兼顾开发效率、样式稳定性和可维护性，是 V4 项目唯一推荐的自定义方案。

Tailwind CSS V4 自定义样式 · 速查表

和上一篇文章配套，精简、可直接复制，遵循官方 V4 规范

✅ 指令总览

⚠️ 注意：V4 不再推荐 @layer utilities，定义工具类一律用 @utility

1. @theme 主题变量（颜色/尺寸/圆角）

@import "tailwindcss";@theme {
  --color-brand-500: #165DFF;
  --color-brand-600: #0E42D2;
  --radius-card: 16px;
  --shadow-card: 0 4px 20px rgba(0,0,0,0.08);
}

使用：

<div class="bg-brand-500 rounded-[var(--radius-card)] shadow-card"></div>

暗色覆盖：

.dark {
  @theme {
    --color-page-bg: #121212;
  }
}

2. @utility 自定义工具类（最常用）

@utility card-base {
  padding: 1.5rem;
  border-radius: var(--radius-card);
  background: white;
  box-shadow: var(--shadow-card);
  transition: all 0.2s;
  &:hover {
    transform: translateY(-4px);
  }
  &:active {
    transform: translateY(0);
  }
}

使用：

<div class="card-base hover:shadow-lg"></div>

✅ 支持所有内置变体：dark:card-base、md:card-base

3. @custom-variant 自定义变体

/* pressed: 按压激活 */
@custom-variant pressed {
  &:active {
    @slot;
  }
}

使用：

<button class="pressed:scale-95 pressed:opacity-80 transition">按钮</button>

父元素状态变体示例（dark）

@custom-variant theme-dark {
  &:where(.dark *) {
    @slot;
  }
}

<div class="theme-dark:text-white"></div>

4. @layer base（基础标签样式）

@layer base {
  body {
    @apply bg-zinc-50 text-zinc-800;
  }
  h1 {
    @apply text-3xl font-bold;
  }
}

5. @layer components（组件样式）

@layer components {
  .btn-primary {
    @apply bg-brand-500 text-white px-5 py-2 rounded-lg transition-all;
    &:hover {
      @apply bg-brand-600;
    }
  }
}

<button class="btn-primary">提交</button>

特点：组件样式优先级低于工具类，写 class="btn-primary bg-red-500" 时，bg-red-500 可以覆盖。

6. 任意值内联样式（临时一次性样式）

语法：[属性:值]

<div class="w-[320px] h-[180px] rounded-[20px] shadow-[0_8px_24px_rgba(22,93,255,0.15)]">
  任意值
</div><p class="text-[18px] leading-[1.8] text-[#165DFF]"></p>
<!-- 任意值 + 透明度 -->
<div class="bg-[#722ED1]/70"></div>

适合一次性特殊样式，不要大量复用（复用请写@utility）

7. 原生CSS（读取tailwind主题变量）

.custom-box {
  background: var(--color-brand-500);
  border-radius: var(--radius-card);
}
.custom-box:hover {
  filter: brightness(1.05);
}

🚫 避坑速记

1. ❌ 不要用 @layer utilities 创建工具类 → 替换为 @utility
2. ❌ @utility 名字只能小写字母+数字，不能带 [ ]，不能用特殊符号
3. ❌ 透明度写法中间不能空格：bg-blue-500/50，不是 bg-blue-500 / 50
4. ❌ @utility、@custom-variant、@theme 必须写在顶层，不能嵌套
5. ✅ 优先级顺序：@utility工具类 > @layer components组件 > @layer base基础样式
6. ✅ CDN模式：全部指令可用；tree-shaking（清除未使用样式）仅 NPM 打包生效
7. ✅ 自定义主题变量，可以 JS 修改，支持动态换肤

📌 选型一句话口诀

临时样式用方括号，全局工具 @utility；
自定义变体 variant，基础标签写 base；
可覆盖组件 components，主题变量 @theme。