name: setup-tailwind-typescript description: > 在 Next.js 或 React 项目中配置 Tailwind CSS 与 TypeScript。涵盖安装、 配置、自定义主题扩展、组件模式及类型安全样式工具。适用于为现有 TypeScript 项目添加 Tailwind CSS、为项目设计系统自定义 Tailwind 主题、 设置类型安全组件样式模式，或配置 Tailwind 插件和扩展。 license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: web-dev complexity: basic language: TypeScript tags: tailwind, typescript, css, styling, configuration locale: zh-CN source_locale: en source_commit: 6f65f316 translator: claude-opus-4-6 translation_date: 2026-03-16

配置 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 — 部署已完成样式的应用