Tailwind CSS v4 安装 (NPM) 学习笔记

一、Tailwind CSS v4 核心变化

v4 是一次全面重构，相比 v3 有重大架构变化：

对比项 v3 v4
配置方式 tailwind.config.js CSS 原生配置 (@theme)
引入方式 @tailwind base/components/utilities @import "tailwindcss"
编译引擎 PostCSS 插件 全新 Rust 引擎 (Oxide)
构建速度 基准 快 10 倍+
内容检测 content 配置项 自动检测（无需配置）
CSS 层 @layer components 等 @layer theme/base/components/utilities
颜色系统 固定色阶 OKLCH 色彩空间，自动生成色阶
暗色模式 darkMode: 'class' @variant dark / @custom-variant
浏览器兼容 PostCSS 转换 原生 CSS 特性（需现代浏览器）

二、安装步骤

1. 初始化项目

mkdir my-project && cd my-project
npm init -y

2. 安装 Tailwind CSS v4

npm install tailwindcss @tailwindcss/cli

v4 将 CLI 独立为 @tailwindcss/cli 包，不再内置在 tailwindcss 中。

3. 创建 CSS 入口文件

/* src/input.css */
@import "tailwindcss";

v4 只需一行，替代了 v3 的三行 @tailwind 指令。

4. 创建 HTML 文件

<!-- src/index.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Tailwind CSS v4</title>
  <link rel="stylesheet" href="../dist/output.css">
</head>
<body class="bg-gray-50 text-gray-900 min-h-screen">
  <div class="max-w-4xl mx-auto py-12 px-4">
    <h1 class="text-4xl font-bold text-blue-600 mb-4">Hello Tailwind v4!</h1>
    <p class="text-lg text-gray-600">使用 NPM 方式安装的 Tailwind CSS v4。</p>
  </div>
</body>
</html>

5. 构建并监听

# 开发模式（监听文件变化）
npx @tailwindcss/cli -i src/input.css -o dist/output.css --watch

# 生产构建（压缩输出）
npx @tailwindcss/cli -i src/input.css -o dist/output.css --minify

6. 配置 npm scripts

{
  "scripts": {
    "dev": "@tailwindcss/cli -i src/input.css -o dist/output.css --watch",
    "build": "@tailwindcss/cli -i src/input.css -o dist/output.css --minify"
  }
}

npm run dev    # 开发
npm run build  # 生产构建

三、v4 配置方式（CSS 原生）

v4 不再使用 tailwind.config.js，所有配置在 CSS 中完成。

1. @theme — 自定义设计令牌

/* src/input.css */
@import "tailwindcss";

@theme {
  /* 自定义颜色 */
  --color-brand-50: #eff6ff;
  --color-brand-100: #dbeafe;
  --color-brand-200: #bfdbfe;
  --color-brand-500: #3b82f6;
  --color-brand-600: #2563eb;
  --color-brand-700: #1d4ed8;
  --color-brand-900: #1e3a8a;

  /* 自定义字体 */
  --font-sans: "Microsoft YaHei", system-ui, sans-serif;
  --font-mono: "Fira Code", monospace;

  /* 自定义间距 */
  --spacing-18: 4.5rem;
  --spacing-128: 32rem;

  /* 自定义断点 */
  --breakpoint-xs: 475px;
  --breakpoint-3xl: 1920px;

  /* 自定义圆角 */
  --radius-4xl: 2rem;

  /* 自定义动画 */
  --animate-fade-in: fade-in 0.5s ease-out;
}

@keyframes fade-in {
  from { opacity: 0; transform: translateY(10px); }
  to   { opacity: 1; transform: translateY(0); }
}

使用效果：

<div class="bg-brand-500 text-white px-4 py-2 rounded-4xl animate-fade-in">
  品牌按钮
</div>

2. 命名规则

v4 的 @theme 使用 CSS 自定义属性，命名规则：

--{类别}-{名称}
类别 前缀 示例 生成的工具类
颜色 --color- --color-brand-500 bg-brand-500 text-brand-500 border-brand-500
字体 --font- --font-sans font-sans
间距 --spacing- --spacing-128 p-128 m-128 w-128
断点 --breakpoint- --breakpoint-xs xs: 前缀
圆角 --radius- --radius-4xl rounded-4xl
动画 --animate- --animate-fade-in animate-fade-in
阴影 --shadow- --shadow-soft shadow-soft

3. 覆盖默认值

@import "tailwindcss";

@theme {
  /* 覆盖默认蓝色 */
  --color-blue-500: #0ea5e9;

  /* 覆盖默认 sans 字体 */
  --font-sans: "Inter", "Microsoft YaHei", system-ui, sans-serif;
}

4. @theme inline — 仅使用自定义值

@theme inline {
  /* inline 模式：不引入默认主题，只使用自定义值 */
  --color-primary: #3b82f6;
  --color-secondary: #8b5cf6;
}

四、v4 自定义样式

1. @layer 使用

@import "tailwindcss";

/* 基础层 — 重置/全局样式 */
@layer base {
  body {
    @apply bg-gray-50 text-gray-900;
  }
  h1, h2, h3 {
    @apply font-bold tracking-tight;
  }
}

/* 组件层 — 可复用组件样式 */
@layer components {
  .btn {
    @apply font-semibold py-2 px-4 rounded-lg transition duration-200 inline-block;
  }
  .btn-primary {
    @apply bg-blue-500 hover:bg-blue-700 text-white;
  }
  .btn-danger {
    @apply bg-red-500 hover:bg-red-700 text-white;
  }
  .btn-outline {
    @apply border-2 border-blue-500 text-blue-500 hover:bg-blue-50;
  }
  .card {
    @apply bg-white rounded-xl shadow-sm border border-gray-200 p-6;
  }
  .input-field {
    @apply w-full px-3 py-2 border border-gray-300 rounded-lg
           focus:border-blue-500 focus:ring-2 focus:ring-blue-200
           outline-none transition;
  }
}

/* 工具层 — 自定义工具类 */
@layer utilities {
  .text-balance {
    text-wrap: balance;
  }
}

2. @variant 自定义变体

@import "tailwindcss";

/* 自定义暗色模式变体 */
@custom-variant dark (&:where(.dark, .dark *));

/* 自定义 hocus 变体（hover + focus） */
@custom-variant hocus (&:hover, &:focus);

<!-- 使用自定义变体 -->
<button class="bg-blue-500 hocus:bg-blue-700 text-white px-4 py-2 rounded-lg">
  悬停或聚焦变色
</button>

3. @utility 自定义工具类

@import "tailwindcss";

@utility glass {
  background: rgba(255, 255, 255, 0.2);
  backdrop-filter: blur(12px);
  border: 1px solid rgba(255, 255, 255, 0.3);
}

@utility text-shadow {
  text-shadow: 0 2px 4px rgba(0, 0, 0, 0.3);
}

<div class="glass rounded-xl p-6">毛玻璃效果</div>
<h1 class="text-shadow text-4xl font-bold">文字阴影</h1>

五、v4 自动内容检测

v4 无需配置 content，自动检测项目中的模板文件。

检测范围

自动扫描以下文件类型：

*.html, *.js, *.ts, *.jsx, *.tsx, *.vue, *.svelte, *.mdx, *.astro

排除路径

如需排除 node_modules 等目录，v4 默认已排除，也可手动指定：

@import "tailwindcss";

@source "../node_modules/my-ui-lib/**/*.js";
@source ignore "../legacy/**/*.html";

六、与构建工具集成

1. Vite 集成（推荐）

npm install tailwindcss @tailwindcss/vite

// vite.config.js
import tailwindcss from '@tailwindcss/vite';

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

/* src/input.css */
@import "tailwindcss";

Vite 会自动处理 CSS，无需手动指定输出路径。

2. PostCSS 集成

npm install tailwindcss @tailwindcss/postcss

// postcss.config.js
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

3. Webpack 集成

npm install tailwindcss @tailwindcss/postcss postcss-loader

// postcss.config.js
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader', 'postcss-loader'],
      },
    ],
  },
};

七、完整项目示例

项目结构

my-project/
├── package.json
├── src/
│   ├── input.css
│   └── index.html
└── dist/
    └── output.css    （构建生成）

input.css

@import "tailwindcss";

/* ===== 自定义主题 ===== */
@theme {
  --color-brand-50: #eff6ff;
  --color-brand-500: #3b82f6;
  --color-brand-600: #2563eb;
  --color-brand-700: #1d4ed8;
  --color-brand-900: #1e3a8a;

  --font-sans: "Microsoft YaHei", system-ui, sans-serif;

  --animate-fade-in: fade-in 0.5s ease-out;
  --animate-slide-up: slide-up 0.3s ease-out;
}

@keyframes fade-in {
  from { opacity: 0; transform: translateY(10px); }
  to   { opacity: 1; transform: translateY(0); }
}

@keyframes slide-up {
  from { opacity: 0; transform: translateY(20px); }
  to   { opacity: 1; transform: translateY(0); }
}

/* ===== 自定义变体 ===== */
@custom-variant dark (&:where(.dark, .dark *));

/* ===== 自定义工具类 ===== */
@utility glass {
  background: rgba(255, 255, 255, 0.15);
  backdrop-filter: blur(12px);
  border: 1px solid rgba(255, 255, 255, 0.2);
}

/* ===== 组件样式 ===== */
@layer components {
  .btn {
    @apply font-semibold py-2.5 px-5 rounded-lg transition duration-200
           inline-flex items-center gap-2;
  }
  .btn-brand {
    @apply bg-brand-500 hover:bg-brand-700 text-white;
  }
  .btn-outline {
    @apply border-2 border-brand-500 text-brand-500 hover:bg-brand-50;
  }
  .card {
    @apply bg-white dark:bg-gray-800 rounded-xl shadow-sm
           border border-gray-200 dark:border-gray-700 p-6
           animate-fade-in;
  }
  .input-field {
    @apply w-full px-3 py-2.5 border border-gray-300 dark:border-gray-600
           rounded-lg bg-white dark:bg-gray-800
           focus:border-brand-500 focus:ring-2 focus:ring-brand-500/20
           outline-none transition;
  }
}

index.html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Tailwind CSS v4 项目</title>
  <link rel="stylesheet" href="../dist/output.css">
</head>

<body class="bg-gray-50 dark:bg-gray-900 text-gray-900 dark:text-white min-h-screen">

  <!-- 导航栏 -->
  <nav class="bg-white/80 dark:bg-gray-800/80 backdrop-blur-md shadow-sm sticky top-0 z-50">
    <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
      <div class="flex justify-between h-16 items-center">
        <span class="text-xl font-bold text-brand-500">MyApp</span>
        <div class="flex items-center gap-4">
          <a href="#" class="text-gray-700 dark:text-gray-300 hover:text-brand-500 transition">首页</a>
          <a href="#" class="text-gray-700 dark:text-gray-300 hover:text-brand-500 transition">产品</a>
          <button class="btn btn-brand">登录</button>
        </div>
      </div>
    </div>
  </nav>

  <!-- Hero 区域 -->
  <section class="max-w-7xl mx-auto px-4 py-20 text-center">
    <h1 class="text-5xl font-bold mb-6 animate-fade-in">
      欢迎使用 <span class="text-brand-500">Tailwind CSS v4</span>
    </h1>
    <p class="text-xl text-gray-600 dark:text-gray-400 mb-8 max-w-2xl mx-auto animate-slide-up">
      全新 Rust 引擎，CSS 原生配置，构建速度提升 10 倍
    </p>
    <div class="flex justify-center gap-4 animate-slide-up">
      <button class="btn btn-brand">开始使用</button>
      <button class="btn btn-outline">了解更多</button>
    </div>
  </section>

  <!-- 卡片区域 -->
  <section class="max-w-7xl mx-auto px-4 pb-20">
    <div class="grid grid-cols-1 md:grid-cols-3 gap-6">
      <div class="card">
        <div class="text-3xl mb-3">⚡</div>
        <h3 class="font-semibold text-lg mb-2">极速构建</h3>
        <p class="text-gray-600 dark:text-gray-400">Rust 引擎驱动，构建速度提升 10 倍以上</p>
      </div>
      <div class="card">
        <div class="text-3xl mb-3">🎨</div>
        <h3 class="font-semibold text-lg mb-2">CSS 原生配置</h3>
        <p class="text-gray-600 dark:text-gray-400">告别 JS 配置文件，一切在 CSS 中完成</p>
      </div>
      <div class="card">
        <div class="text-3xl mb-3">🚀</div>
        <h3 class="font-semibold text-lg mb-2">自动检测</h3>
        <p class="text-gray-600 dark:text-gray-400">无需配置 content，自动扫描模板文件</p>
      </div>
    </div>
  </section>

</body>
</html>

八、v3 → v4 迁移要点

v3 v4 说明
@tailwind base; @tailwind components; @tailwind utilities; @import "tailwindcss"; 一行替代三行
tailwind.config.js @theme { } 配置迁移到 CSS
content: [...] 自动检测 无需配置
darkMode: 'class' @custom-variant dark (...) CSS 中声明
plugins: [require(...)] @plugin "..." 或 @import CSS 方式引入
@apply @apply（不变） 语法兼容
npx tailwindcss ... npx @tailwindcss/cli ... CLI 独立包
theme.extend.colors --color-* CSS 变量命名
theme.extend.fontFamily --font-* CSS 变量命名
theme.extend.spacing --spacing-* CSS 变量命名

迁移命令

# 官方迁移工具（自动转换配置文件）
npx @tailwindcss/upgrade

该工具会自动将 tailwind.config.js 转换为 @theme CSS 配置，并更新模板中的类名变化。

九、常见问题

1. v4 是否还需要 PostCSS？

不必须。v4 有独立 CLI 和 Vite 插件，PostCSS 只是可选集成方式之一。

2. v4 能否继续使用 tailwind.config.js？

不推荐。v4 完全基于 CSS 配置，JS 配置文件不再被识别。使用 @tailwindcss/upgrade 工具自动迁移。

3. 浏览器兼容性

v4 使用了 CSS 原生嵌套、@layer、:where() 等现代特性，需要现代浏览器（Chrome 120+、Firefox 117+、Safari 17.2+）。如需兼容旧浏览器，仍需 PostCSS 兼容插件。

4. 产出体积

v4 的按需生成更加精准，典型项目产出 5-15KB（压缩后），比 v3 更小。

# npm # 前端 # node.js
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

AtomGit 首发开源｜光轮智能发布全球首个十万小时级全模态人类行为开源数据集 EgoSuite-Open100K

avatar AtomGit开源社区
cover

构筑赋能金融行业应用 Agent｜20 强决战北京，一场金融 Agent 的硬核答卷

avatar AtomGit开源社区
cover

昇腾 0 Day 支持 Hunyuan4-preview，770B MoE 旗舰模型开源即适配

avatar AtomGit开源社区