Tailwind CSS V4 完整配置指南

Tailwind CSS V4 最大的革命性升级，就是彻底重构了配置体系。

如果你熟悉 V3，你一定习惯依靠 tailwind.config.js 写颜色、断点、尺寸。但在 V4 中，官方不再默认依赖 JS 配置文件，全面支持原生 CSS 配置，无需任何 JS 代码即可完成主题扩展、自定义工具、插件引入，配置更直观、更简洁、更统一。

本文带你从零吃透 V4 全部配置方式，包含：CSS 原生配置、主题自定义、自定义工具类、插件配置、暗色模式、兼容 V3 旧 JS 配置、常见踩坑点。

一、V4 与 V3 配置的核心区别（必看）

很多配置报错、样式失效，根源就是混用 V3 旧语法。

• V3：配置中心是 tailwind.config.js，必须手动写 content 扫描路径、必须写三段 @tailwind 指令。
• V4：配置中心迁移到 CSS，使用 @theme、@utility、@plugin 指令，JS 配置文件变为可选，自动扫描文件，无需手动配置 content。

V4 标准入口（唯一写法）：

@import "tailwindcss";

二、V4 全新核心配置：@theme（主题自定义）

@theme 是 V4 最核心的配置指令，替代了 V3 的 theme.extend。所有颜色、字体、间距、断点、圆角，全部可以在 CSS 内直接扩展，无需 JS。

规则非常简单：–color-xxx 自定义颜色、–breakpoint-xxx 自定义断点、–font-xxx 自定义字体。

1. 自定义主题颜色

@import "tailwindcss";

@theme {
  /* 自定义主色 */
  --color-brand: #165DFF;
  /* 分级色值 */
  --color-brand-light: #4080ff;
  --color-brand-dark: #0E42D2;
  /* 功能色 */
  --color-success: #00B42A;
  --color-danger: #F53F3F;
}

写完直接使用：text-brand、bg-brand-light、border-danger，和官方内置颜色用法完全一致。

2. 自定义响应式断点

V4 支持直接新增屏幕尺寸，适配大屏、移动端特殊布局：

@theme {
  --breakpoint-3xl: 1920px;
  --breakpoint-xs: 360px;
}

使用：3xl:text-4xl、xs:text-sm

3. 自定义字体、圆角、间距

@theme {
  /* 自定义字体 */
  --font-display: "Microsoft Yahei", sans-serif;
  /* 超大圆角 */
  --radius-xl: 16px;
  /* 自定义间距 */
  --spacing-18: 4.5rem;
}

三、V4 自定义工具类：@utility（官方推荐）

V4 彻底革新自定义工具写法，废弃 V3 的 @layer utilities 作为首选方案，全新 @utility 定义的工具类天然支持 hover:、md:、dark: 所有修饰符，优先级和官方内置工具完全一致。

基础自定义工具

@import "tailwindcss";

/* 文字阴影 */
@utility text-shadow {
  text-shadow: 0 2px 8px rgb(0 0 0 / 0.15);
}

/* 卡片渐变背景 */
@utility card-gradient {
  background: linear-gradient(135deg, #3b82f6, #8b5cf6);
}

使用示例：

<div class="card-gradient text-shadow hover:opacity-90">自定义工具类演示</div>

四、V4 插件配置：@plugin 指令

V4 彻底改变 V3 的插件引入方式，不再需要在 JS 配置文件 require 插件，直接在 CSS 一行引入，更简洁、更直观。

引入官方插件

@import "tailwindcss";

/* 文章排版插件 */
@plugin "@tailwindcss/typography";
/* 表单美化插件 */
@plugin "@tailwindcss/forms";

引入后直接使用 prose、表单美化样式，无需任何 JS 配置。

五、暗色模式配置（darkMode）

V4 依然支持两种暗色模式，兼容 V3 逻辑，但配置方式更简洁。

1. 跟随系统（默认）

无需配置，自动跟随电脑/手机系统明暗主题。

2. 手动切换（业务常用）

需要 JS 控制 html 标签 class 切换暗色模式，需启用 class 模式：

如果使用 JS 配置文件：

export default {
  darkMode: "class"
}

六、兼容旧项目：如何使用 tailwind.config.js（V4 兼容方案）

V4 完全兼容 V3 的 JS 配置文件，但不会自动读取，需要手动通过 @config 指令引入。

适合老项目迁移、需要保留旧配置的场景：

@import "tailwindcss";

// 手动加载本地 JS 配置文件
@config "./tailwind.config.js";

引入后，原本 V3 的所有 theme、plugins 配置全部生效，实现无缝迁移。

七、V4 新增 @source 路径配置

V4 默认自动扫描项目所有源码，无需配置 content。如果需要手动指定扫描目录、忽略目录，使用 @source 指令：

@import "tailwindcss";

// 手动指定扫描路径
@source "./src/**/*.{vue,js,ts,html}";
// 忽略指定目录
@source !"./src/ignore/**";

替代 V3 的 content 数组，更简洁直观。

八、V4 配置完整汇总模板（可直接复用）

这是企业级 V4 项目通用完整配置，复制即可直接使用：

@import "tailwindcss";

// 1. 加载旧 JS 配置（可选）
@config "./tailwind.config.js";

// 2. 手动指定扫描路径（可选）
@source "./src/**/*.{vue,js,ts,html}";

// 3. 加载官方插件
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

// 4. 自定义主题
@theme {
  --color-brand: #165DFF;
  --color-success: #00B42A;
  --color-danger: #F53F3F;
  --breakpoint-3xl: 1920px;
}

// 5. 自定义工具类
@utility text-shadow {
  text-shadow: 0 2px 8px rgb(0 0 0 / 0.15);
}

九、V4 配置高频踩坑点

• 禁止混用 V3 三段指令：V4 只能用 @import "tailwindcss"，写 @tailwind base 会直接报错。
• JS 配置文件不会自动加载：V4 必须用 @config 手动引入，否则不生效。
• 废弃 corePlugins：V4 不再支持关闭核心插件的旧配置，统一通过 CSS 层叠覆盖实现。
• 自定义工具优先 @utility：不要再大量使用 @layer utilities，兼容性和修饰符支持不如新指令。
• 修改配置无需重启较少：CSS 配置实时生效，仅修改外部 config.js 需要重启服务。

十、V4 与 V3 配置对照表

总结

Tailwind CSS V4 的配置核心变化就是 「从 JS 配置转向 CSS 原生配置」。

新版本舍弃了 V3 繁琐的配置文件、强制扫描路径、冗余依赖，通过 @theme、@utility、@plugin、@config 四大指令，把所有配置收拢在样式入口文件中，逻辑更集中、写法更统一、上手门槛更低。

新项目直接使用 V4 全套 CSS 配置即可；老项目迁移只需添加 @config 兼容旧配置，平滑升级无压力。

拓展阅读：
《Tailwind CSS V4 安装(NPM)》
《Tailwind CSS V4 安装(CDN)》