自学教程

Tailwind CSS 指令与函数

Tailwind CSS 教程

Tailwind CSS V4 指令与函数完全指南

Tailwind CSS V4 大量全新CSS指令（At‑rules）与内置函数，把绝大部分配置从JS迁移到CSS源码中。理解各类指令、函数，是掌握V4自定义主题、自定义工具类、变体、源扫描的基础。

本文参考官方文档，区分全新V4指令、兼容V3旧指令、内置函数，同时说明CDN浏览器包的限制、NPM构建环境差异，配套大量可复制示例、避坑要点。

一、指令总览

指令是以@开头的CSS规则，分为：核心新指令、兼容旧指令、加载外部资源指令。

指令作用备注
@import导入Tailwind或者其他CSS文件V4入口，@import "tailwindcss"
@theme定义设计令牌：颜色、字体、断点、阴影等V4核心，生成CSS变量
@source控制源文件扫描逻辑补充扫描路径、黑名单、白名单强制生成类
@utility定义自定义工具类替代V3的@layer utilities，天然支持hover/md等变体
@variant在普通CSS规则内部使用变体写在选择器{}内部
@custom‑variant注册全局自定义变体修饰符生成xxx:修饰符，例如theme‑midnight:
@apply把工具类内联到自定义CSS规则中NPM构建可用，CDN浏览器包不支持
@reference引用全局主题，不重复输出CSS，用于Vue/Svelte单文件组件解决SFC中拿不到@theme/@utility定义问题
@plugin加载JS编写的外部插件包（兼容V3生态）只能传包名字符串，不能写{}内嵌CSS代码
@config读取旧版tailwind.config.js配置迁移老项目用，新工程不推荐
@layerCSS原生层base/components/utilitiesV4不再劫持@layer，自定义工具优先用@utility

二、核心指令详解与示例

1. @import 导入入口

V4项目CSS第一行，导入tailwind内核。也支持指定扫描基准路径。

/* 基础导入 */
@import "tailwindcss";/* 指定扫描基准目录，monorepo场景 */
@import "tailwindcss" source("../src");
/* 关闭自动扫描，全部手动@source */
@import "tailwindcss" source(none);

2. @theme 定义主题令牌（V4最重要）

在@theme{}内部定义颜色、字体、断点、圆角、阴影，自动生成CSS变量，可JS运行时动态修改。变量前缀约定：--color‑、--font‑、--breakpoint‑、--radius‑等。

@import "tailwindcss";
@theme {
  --color-brand-500: #165DFF;
  --color-brand-600: #0E42D2;
  --font-display: "Inter", system‑ui, sans‑serif;
  --breakpoint‑3xl: 1920px;
  --radius‑card: 16px;
}

使用：bg‑brand‑500 font‑display rounded‑card；也可以原生CSS中var(--color‑brand‑500)读取。

3. @source 源文件扫描控制

V4取消config的content配置，使用@source，可以追加扫描目录、忽略目录、强制生成类名（白名单inline）、排除类名（黑名单）。

@import "tailwindcss";
/* 扫描node_modules内部UI库 */
@source "../node_modules/@company/ui‑lib";/* 忽略旧业务目录 */
@source not "../src/components/legacy";
/* 强制生成underline工具类（兜底） */
@source inline("underline");
/* 带hover变体批量生成 */
@source inline("{hover:,}bg‑red‑{50,{100..900..100},950}");

⚠️注意：@source仅NPM/Vite/PostCSS构建环境生效，CDN浏览器包完全无效。

4. @utility 自定义工具类（V4推荐）

定义全局工具，自动支持所有变体：hover:md:dark:，替代V3 @layer utilities，支持嵌套伪类&:hover、&:active。必须写在CSS顶层，禁止嵌套到其他指令内部。

@import "tailwindcss";
@utility card‑base {
  padding: 1.25rem;
  border‑radius: var(--radius‑card);
  box‑shadow: 0 4px 20px rgba(0,0,0,0.08);
  &:hover {
    transform: translateY(-4px);
  }
}

使用：<div class="card‑base md:card‑base hover:card‑base"></div>

5. @variant 局部变体（写在规则内部）

在普通CSS选择器内部使用，给一段CSS应用hover、dark等变体条件，不要和@custom‑variant混淆。

.demo‑box {
  background: white;
  @variant dark {
    background: #121212;
  }
}

6. @custom‑variant 注册全局变体修饰符

注册全局可复用的修饰符，生成xxx:语法，例如自定义主题、设备条件。@slot占位代表要应用的工具类样式。支持简写一行写法与块写法。

@import "tailwindcss";
/* 简写 */
@custom‑variant theme‑midnight (&:where([data‑theme="midnight"] *));/* 完整块写法 */
@custom‑variant pressed {
  &:active {
    @slot;
  }
}

使用：pressed:scale‑95 theme‑midnight:text‑white

7. @apply 将工具类内联到自定义CSS

把多个Tailwind工具类直接展开到自定义CSS选择器中。

.btn {
  @apply px‑4 py‑2 rounded‑lg font‑medium transition‑all;
}
  • ✅ NPM/Vite构建环境可用
  • ❌ CDN浏览器包不支持@apply，会报错
  • ❌ 在CSS modules / Vue SFC中需要配合@reference，否则找不到主题与自定义工具

8. @reference 引用（Vue / Svelte单文件组件）

单文件组件的style块中，引用全局CSS，获取@theme/@utility/@custom‑variant的定义，但不会重复输出CSS产物，避免样式重复打包。

Vue SFC示例：

<template>
  <h1>测试标题</h1>
</template>
<style>
@reference "../../src/app.css";
h1 {
  @apply text‑3xl font‑bold text‑brand‑500;
}
</style>

9. @plugin 加载JS插件（兼容V3）

仅用于加载外部JS插件包，参数是字符串包路径。V4没有@plugin name {}内嵌CSS块语法，不要写大括号包裹@utility/@variant，会报cannot be nested错误。

@import "tailwindcss";
@plugin "@tailwindcss/typography";

10. @config 读取V3配置文件（迁移老项目）

老项目迁移，读取tailwind.config.js。注意：config中的corePlugins、safelist、separator不再支持，白名单改用@source inline()。

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

11. @layer CSS原生层 base / components / utilities

V4使用浏览器原生CSS cascade layers，不再劫持@layer。

  • @layer base：用于html、body、h1等原生标签重置基础样式。
  • @layer components：用于自定义组件类，优先级低于工具类，允许工具类覆盖。
  • ❌ V4不推荐在@layer utilities {}里面写自定义工具类，优先使用顶层@utility指令。
@layer base {
  body {
    @apply bg‑zinc‑50 text‑zinc‑800;
  }
}@layer components {
  .btn‑demo {
    padding: 0.5rem 1rem;
    border‑radius: 8px;
  }
}

三、V4内置构建函数

1. –alpha() 颜色透明度函数

调整CSS变量颜色透明度，底层编译为color‑mix。

.box {
  background: --alpha(var(--color‑blue‑500) / 50%);
}

2. –spacing() 间距函数

读取主题间距刻度，1单位=0.25rem。可以配合calc在任意值中使用。

.box {
  margin: --spacing(4);
}/* HTML任意值中使用 */
<div class="py‑[calc(--spacing(4)‑2px)]"></div>

3. theme() 访问主题（已不推荐）

兼容V3遗留函数，读取主题值；官方建议优先直接使用CSS变量var(--color‑xxx)替代theme()函数，theme()未来会逐步废弃。

/* 旧写法，不推荐 */
.old {
  background‑color: theme("colors.blue‑500");
}
/* V4推荐写法 */
.new {
  background‑color: var(--color‑blue‑500);
}

四、环境差异：CDN浏览器包 vs NPM构建环境

能力CDN @tailwindcss/browser@4NPM/Vite构建
@import / @theme / @utility / @custom‑variant✅可用✅可用
@apply❌不支持✅可用
@source（扫描源文件、白名单）❌无效✅可用
@reference❌无效✅可用
@plugin加载npm包插件❌无效✅可用

> CDN仅适合原型演示；生产环境必须NPM/Vite构建。CDN中遇到Cannot apply unknown utility class报错，很多是因为CDN不支持@apply读取@theme自定义颜色，改用原生var()变量写法规避。

五、高频避坑清单

  • ❌错误：@plugin myname { @utility xxx{} }；V4没有这种内嵌块语法，@plugin只能加载外部JS包。
  • ❌错误：把@utility / @custom‑variant嵌套写在其他{}内部；二者必须顶层指令，否则抛出cannot be nested。
  • ❌CDN环境使用@apply读取@theme定义的自定义颜色，会报找不到工具类；CDN避免使用@apply，改用原生CSS var()变量。
  • ✅Vue/Svelte单文件组件style块，需要使用@reference引用全局CSS，否则读不到@theme、@utility。
  • ✅自定义工具类优先@utility，不要再大量写@layer utilities。
  • ✅尽量用CSS变量var(--color‑xxx)替代废弃的theme()函数。
  • ❌不要在CDN环境使用@source，它是编译期构建指令。

六、完整最小NPM工程示例main.css

@import "tailwindcss";/* 主题定义 */
@theme {
  --color‑brand‑500: #165DFF;
  --radius‑card: 16px;
}
/* 自定义工具 */
@utility card‑demo {
  padding: 1.5rem;
  border‑radius: var(--radius‑card);
  background: white;
  box‑shadow: 0 4px 20px rgba(0,0,0,0.08);
}
/* 自定义全局变体 */
@custom‑variant pressed {
  &:active {
    @slot;
  }
}
/* 基础层 */
@layer base {
  body {
    @apply bg‑zinc‑50;
  }
}
/* 组件层 */
@layer components {
  .btn‑primary {
    @apply px‑4 py‑2 rounded‑lg text‑white transition‑all;
    background: var(--color‑brand‑500);
    &:hover {
      background: #0E42D2;
    }
  }
}

总结

Tailwind CSS V4将绝大多数配置迁移到CSS层面，核心指令记忆：

  • 导入入口：@import "tailwindcss"
  • 定义主题令牌：@theme {}
  • 控制源扫描：@source
  • 自定义工具类：@utility（顶层）
  • 自定义全局变体修饰符：@custom‑variant（顶层）
  • 组件内引用全局：@reference
  • 加载JS插件：@plugin "包名"
  • 内联工具类：@apply（NPM构建可用，CDN不可用）

同时区分CDN原型环境与NPM构建环境差异，可以避开绝大多数编译报错。

附录：Tailwind CSS V4 指令与函数速查表

/* ========== 导入 ========== */
@import "tailwindcss";
@import "tailwindcss" source("../src");
@import "tailwindcss" source(none);/* ========== @theme 主题令牌 ========== */
@theme {
  --color-brand-500: #165DFF;
  --radius-card:16px;
  --breakpoint-3xl:1920px;
}
/* ========== @source 源扫描（仅NPM构建） ========== */
@source "../node_modules/@xxx/ui";
@source not "../src/legacy";
@source inline("underline");
@source inline("{hover:,}bg-red-{50,{100..900..100},950}");
/* ========== @utility 自定义工具【顶层】 ========== */
@utility card-base {
  padding:1.5rem;
  &:hover { transform:translateY(-4px); }
}
/* ========== @custom‑variant 全局变体修饰符【顶层】 ========== */
@custom‑variant pressed {
  &:active { @slot; }
}
/* ========== @variant 局部变体（写在选择器内部） ========== */
.box {
  @variant dark { background:#111; }
}
/* ========== @apply 内联工具（CDN不可用） ========== */
.btn {
  @apply px‑4 py‑2 rounded‑lg;
}
/* ========== @reference SFC组件引用，不输出CSS ========== */
@reference "../../app.css";
/* ========== @plugin 加载JS插件，只写字符串包名 ========== */
@plugin "@tailwindcss/typography";
/* ========== @config 读取V3 config（迁移老项目） ========== */
@config "./tailwind.config.js";
/* ========== @layer CSS原生层 ========== /
@layer base { / html body h1全局标签 / }
@layer components { / 自定义组件类 */ }
/* ========== V4内置函数 ========== */
.box1 {
  background: --alpha(var(--color-blue-500)/50%);
  margin: --spacing(4);
}
/* ❌ 不推荐，优先var() */
.box2 {
  background‑color: theme("colors.blue‑500");
}

⚠️ 重要提醒

  1. @utility、@custom‑variant必须写在CSS顶层，禁止嵌套在任何大括号内部，否则报cannot be nested。
  2. @apply、@source、@reference、@plugin加载npm包，CDN浏览器环境全部无效，仅NPM/Vite构建环境生效。
  3. @plugin只接受字符串包路径，V4没有@plugin name { ... }内嵌CSS块语法。
标签：

0 条笔记