配置 Tailwind CSS 与 TypeScript

在 TypeScript 项目中配置 Tailwind CSS，包含自定义主题、工具函数和类型安全模式。

适用场景

• 为现有 TypeScript 项目添加 Tailwind CSS
• 为项目设计系统自定义 Tailwind 主题
• 设置类型安全组件样式模式
• 配置 Tailwind 插件和扩展

输入

• 必需：TypeScript 项目（Next.js、Vite 或独立 React）
• 可选：设计系统令牌（颜色、间距、字体）
• 可选：要包含的 Tailwind 插件

步骤

第 1 步：安装 Tailwind CSS

npm install -D tailwindcss @tailwindcss/postcss postcss

对于 Next.js（如果尚未包含）：

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

预期结果：

tailwindcss

、

postcss

和

autoprefixer

安装为开发依赖项。对于 Next.js，

npx tailwindcss init -p

生成

tailwind.config.ts

和

postcss.config.js

。

失败处理： 如果

npx tailwindcss init

失败，先用

npm install -D tailwindcss

安装 Tailwind，再重试。如果使用 monorepo，从应用根目录运行命令，而非工作区根目录。

第 2 步：配置 tailwind.config.ts

import type { Config } from "tailwindcss";

const config: Config = {
  content: [
    "./src/pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/components/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/app/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  theme: {
    extend: {
      colors: {
        primary: {
          50: "#eff6ff",
          100: "#dbeafe",
          500: "#3b82f6",
          600: "#2563eb",
          700: "#1d4ed8",
          900: "#1e3a5f",
        },
        secondary: {
          500: "#6366f1",
          600: "#4f46e5",
        },
      },
      fontFamily: {
        sans: ["Inter", "system-ui", "sans-serif"],
        mono: ["JetBrains Mono", "monospace"],
      },
      spacing: {
        "18": "4.5rem",
        "88": "22rem",
      },
    },
  },
  plugins: [],
};

export default config;

预期结果：

tailwind.config.ts

的

content

数组与项目文件位置匹配，

theme.extend

下有自定义颜色和字体，并通过

Config

导入正确的 TypeScript 类型。

失败处理： 如果自定义类未渲染，验证

content

路径是否与实际目录结构匹配。路径为相对于项目根目录的 glob 模式。路径缺失意味着 Tailwind 不会扫描这些文件中的类用法。

第 3 步：设置全局样式

编辑

src/app/globals.css

：

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  html {
    @apply antialiased;
  }

  body {
    @apply bg-white text-gray-900 dark:bg-gray-950 dark:text-gray-100;
  }
}

@layer components {
  .btn-primary {
    @apply bg-primary-600 text-white px-4 py-2 rounded-lg
           hover:bg-primary-700 focus:outline-none focus:ring-2
           focus:ring-primary-500 focus:ring-offset-2
           transition-colors duration-200;
  }
}

预期结果：

globals.css

包含三个 Tailwind 指令（

@tailwind base

、

@tailwind components

、

@tailwind utilities

）以及自定义基础和组件层样式。文件在根布局中被导入。

失败处理： 如果样式未应用，验证

globals.css

是否在

layout.tsx

（或 Pages Router 的

_app.tsx

）中导入。检查 Tailwind 指令是否存在且未被注释。

第 4 步：创建类型安全工具函数

创建

src/lib/cn.ts

：

import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

安装依赖项：

npm install clsx tailwind-merge

组件中的用法：

import { cn } from "@/lib/cn";

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: "primary" | "secondary" | "outline";
}

export function Button({ className, variant = "primary", ...props }: ButtonProps) {
  return (
    <button
      className={cn(
        "px-4 py-2 rounded-lg font-medium transition-colors",
        variant === "primary" && "bg-primary-600 text-white hover:bg-primary-700",
        variant === "secondary" && "bg-secondary-500 text-white hover:bg-secondary-600",
        variant === "outline" && "border border-gray-300 hover:bg-gray-50",
        className
      )}
      {...props}
    />
  );
}

预期结果：

src/lib/cn.ts

导出

cn()

函数。

clsx

和

tailwind-merge

已安装为依赖项。组件使用

cn()

合并类名而不产生冲突。

失败处理： 如果找不到

clsx

或

tailwind-merge

，运行

npm install clsx tailwind-merge

。如果 TypeScript 在

cn.ts

中报类型错误，验证

ClassValue

类型是否从

clsx

导入。

第 5 步：添加深色模式支持

更新

tailwind.config.ts

：

const config: Config = {
  darkMode: "class", // or "media" for system preference
  // ... rest of config
};

切换实现：

"use client";
import { useEffect, useState } from "react";

export function ThemeToggle() {
  const [dark, setDark] = useState(false);

  useEffect(() => {
    document.documentElement.classList.toggle("dark", dark);
  }, [dark]);

  return (
    <button onClick={() => setDark(!dark)}>
      {dark ? "Light" : "Dark"} Mode
    </button>
  );
}

预期结果： 深色模式在亮色和深色主题之间正确切换。

dark

类应用于

<html>

元素，带

dark:

前缀的工具类相应响应。

失败处理： 如果深色模式不切换，验证

tailwind.config.ts

中是否设置了

darkMode: "class"

。确保

dark

类在

<html>

元素（而非

<body>

）上切换。对于系统偏好模式，改用

darkMode: "media"

。

第 6 步：添加插件（可选）

npm install -D @tailwindcss/typography @tailwindcss/forms

// tailwind.config.ts
import typography from "@tailwindcss/typography";
import forms from "@tailwindcss/forms";

const config: Config = {
  // ...
  plugins: [typography, forms],
};

预期结果： 插件安装为开发依赖项并在

tailwind.config.ts

的

plugins

数组中注册。插件提供的类（如 typography 的

prose

、forms 的样式化表单元素）在组件中可用。

失败处理： 如果插件类未渲染，验证插件已安装（

npm ls @tailwindcss/typography

）并已添加到

plugins

数组。更改配置后重启开发服务器。

验证清单

• Tailwind 类在浏览器中正确渲染
• 自定义主题值（颜色、字体、间距）正常工作

• cn()

  工具函数无冲突地合并类名
• 深色模式正确切换
• TypeScript 在配置或组件中无错误
• 生产构建清除未使用的样式

常见问题

• 内容路径缺失：如果类未渲染，检查配置中的

  content

  数组是否与文件位置匹配
• 类冲突：使用

  tailwind-merge

  （通过

  cn()

  ）防止工具类冲突
• 自定义值不生效：确保自定义值在

  extend

  下（添加），而非主题根目录（替换默认值）
• 深色模式不切换：检查

  darkMode

  设置，确认

  dark

  类在

  <html>

  而非

  <body>

  上

相关技能

• scaffold-nextjs-app

  — 配置 Tailwind 前的项目设置

• deploy-to-vercel

  — 部署已完成样式的应用